Changes

Jump to navigation Jump to search
1,046 bytes added ,  22:53, 18 July 2016
Line 1: Line 1: −
NAME
+
== NAME ==
      esmith::util - Utilities for e-smith server and gateway development
+
esmith::util - Utilities for e-smith server and gateway development
   −
VERSION
+
In a root terminal you can do the command below if you want to display the up-to-date content
      This file documents "esmith::util" version 1.4.0
+
perldoc esmith::util
 +
== VERSION ==
 +
This file documents "esmith::util" version 1.4.0
   −
SYNOPSIS
+
== SYNOPSIS ==
          use esmith::util;
+
use esmith::util;
   −
DESCRIPTION
+
== DESCRIPTION ==
      This module provides general utilities of use to developers of the
+
This module provides general utilities of use to developers of the e-smith server and gateway.
      e-smith server and gateway.
     −
GENERAL UTILITIES
+
== GENERAL UTILITIES ==
      setRealToEffective()
+
=== setRealToEffective() ===
   −
      Sets the real UID to the effective UID and the real GID to the effec-
+
Sets the real UID to the effective UID and the real GID to the effective GID.
      tive GID.
     −
      processTemplate({ CONFREF => $conf, TEMPLATE_PATH => $path })
+
=== processTemplate({ CONFREF => $conf, TEMPLATE_PATH => $path }) ===
   −
      Depreacted interface to esmith::templates::processTemplate().
+
Depreacted interface to esmith::templates::processTemplate().
   −
      chownfile($user, $group, $file)
+
=== chownfile($user, $group, $file) ===
   −
      This routine changes the ownership of a file, automatically converting
+
This routine changes the ownership of a file, automatically converting usernames and groupnames to UIDs and GIDs respectively.
      usernames and groupnames to UIDs and GIDs respectively.
     −
      determineRelease()
+
=== determineRelease() ===
   −
      Returns the current release version of the software.
+
Returns the current release version of the software.
   −
NETWORK ADDRESS TRANSLATION UTILITIES
+
=== NETWORK ADDRESS TRANSLATION UTILITIES ===
      IPquadToAddr($ip)
+
=== IPquadToAddr($ip) ===
   −
      Convert IP address from "xxx.xxx.xxx.xxx" notation to a 32-bit integer.
+
Convert IP address from "xxx.xxx.xxx.xxx" notation to a 32-bit integer.
   −
      IPaddrToQuad($address)
+
=== IPaddrToQuad($address) ===
 +
Convert IP address from a 32-bit integer to "xxx.xxx.xxx.xxx" notation.
   −
      Convert IP address from a 32-bit integer to "xxx.xxx.xxx.xxx" notation.
+
=== IPaddrToBackwardQuad($address) ===
   −
      IPaddrToBackwardQuad($address)
+
Convert IP address from a 32-bit integer to reversed "xxx.xxx.xxx.xxx.in-addr.arpa" notation for BIND files.
   −
      Convert IP address from a 32-bit integer to reversed
+
=== computeNetworkAndBroadcast($ipaddr, $netmask) ===
      "xxx.xxx.xxx.xxx.in-addr.arpa" notation for BIND files.
     −
      computeNetworkAndBroadcast($ipaddr, $netmask)
+
Given an IP address and netmask (both in "xxx.xxx.xxx.xxx" format) compute the network and broadcast addresses and output them in the same format.
   −
      Given an IP address and netmask (both in "xxx.xxx.xxx.xxx" format) com-
+
=== computeLocalNetworkPrefix($ipaddr, $netmask) ===
      pute the network and broadcast addresses and output them in the same
  −
      format.
     −
      computeLocalNetworkPrefix($ipaddr, $netmask)
+
Given an IP address and netmask, the computeLocalNetworkPrefix function computes the network prefix for local machines.
   −
      Given an IP address and netmask, the computeLocalNetworkPrefix function
+
i.e. for an IP address of 192.168.8.4 and netmask of 255.255.255.0, this function will return "192.168.8.".
      computes the network prefix for local machines.
     −
      i.e. for an IP address of 192.168.8.4 and netmask of 255.255.255.0,
+
This string is suitable for use in configuration files (such as /etc/proftpd.conf) when the more precise notation  xxx.xxx.xxx.xxx/yyy.yyy.yyy.yyy is not supported.
      this function will return "192.168.8.".
     −
      This string is suitable for use in configuration files (such as
+
=== computeAllLocalNetworkPrefixes ($ipaddress, $netmask) ===
      /etc/proftpd.conf) when the more precise notation
     −
          xxx.xxx.xxx.xxx/yyy.yyy.yyy.yyy
+
Given an IP address and netmask, the computeAllLocalNetworkPrefixes function computes the network prefix or list of prefixes that fully describe the network to which the IP address belongs.
   −
      is not supported.
+
examples:
   −
      computeAllLocalNetworkPrefixes ($ipaddress, $netmask)
+
* for an IP address of 192.168.8.4 and netmask of 255.255.255.0, will return an array with a first (and only) element of "192.168.8".
   −
        Given an IP address and netmask, the computeAllLocalNetworkPrefixes
+
* for an IP address of 192.168.8.4 and netmask of 255.255.254.0, will return the array [ ’192.168.8’, ’192.168.9’ ].
        function computes the network prefix or list of prefixes that
  −
        fully describe the network to which the IP address belongs.
     −
        examples:
+
This array is suitable for use in configuration of tools such as djbdns where other network notations are not supported.
   −
        - for an IP address of 192.168.8.4 and netmask of 255.255.255.0,
+
=== computeLocalNetworkShortSpec($ipaddr, $netmask) ===
        will return an array with a first (and only) element of "192.168.8".
     −
        - for an IP address of 192.168.8.4 and netmask of 255.255.254.0,
+
Given an IP address and netmask, the computeLocalNetworkShortSpec function computes a valid xxx.xxx.xxx.xxx/yyy specifier where yyy is the number of bits specifying the network.
        will return the array [ ’192.168.8’, ’192.168.9’ ].
     −
        This array is suitable for use in configuration of tools such as
+
i.e. for an IP address of 192.168.8.4 and netmask of 255.255.255.0, this function will return "192.168.8.0/24".
        djbdns where other network notations are not supported.
     −
      computeLocalNetworkShortSpec($ipaddr, $netmask)
+
This string is suitable for use in configuration files (such as /etc/proftpd.conf) when the more precise notation xxx.xxx.xxx.xxx/yyy.yyy.yyy.yyy is not supported.
   −
      Given an IP address and netmask, the computeLocalNetworkShortSpec func-
+
=== computeLocalNetworkSpec($ipaddr, $netmask) ===
      tion computes a valid xxx.xxx.xxx.xxx/yyy specifier where yyy is the
  −
      number of bits specifying the network.
     −
      i.e. for an IP address of 192.168.8.4 and netmask of 255.255.255.0,
+
Given an IP address and netmask, the computeLocalNetworkSpec function computes a valid xxx.xxx.xxx.xxx/yyy.yyy.yyy.yyy specifier.
      this function will return "192.168.8.0/24".
     −
      This string is suitable for use in configuration files (such as
+
=== computeNetmaskFromBits ($bits) ===
      /etc/proftpd.conf) when the more precise notation
     −
          xxx.xxx.xxx.xxx/yyy.yyy.yyy.yyy
+
Given a number of bits of network address, calculate the appropriate netmask.
   −
      is not supported.
+
=== computeLocalNetworkReversed($ipaddr, $netmask) ===
   −
      computeLocalNetworkSpec($ipaddr, $netmask)
+
Given an IP address and netmask, the computeLocalNetworkReversed function computes the appropriate DNS domain field.
   −
      Given an IP address and netmask, the computeLocalNetworkSpec function
+
==== NOTE: ====
      computes a valid xxx.xxx.xxx.xxx/yyy.yyy.yyy.yyy specifier.
+
The return value is aligned to the next available byte boundary, i.e.
   −
      computeNetmaskFromBits ($bits)
+
            192.168.8.4/255.255.255.0 returns "8.168.192.in-addr.arpa."
 +
            192.168.8.4/255.255.252.0 returns "168.192.in-addr.arpa."
 +
            192.168.8.4/255.255.0.0  returns "168.192.in-addr.arpa."
 +
            192.168.8.4/255.252.0.0  returns "192.in-addr.arpa."
 +
            192.168.8.4/255.0.0.0    returns "192.in-addr.arpa."
   −
      Given a number of bits of network address, calculate the appropriate
+
This string is suitable for use in BIND configuration files.
      netmask.
     −
      computeLocalNetworkReversed($ipaddr, $netmask)
+
=== computeHostRange($ipaddr, $netmask) ===
   −
      Given an IP address and netmask, the computeLocalNetworkReversed func-
+
Given a network specification (IP address and netmask), compute the total number of hosts in that network, as well as the first and last IP addresses in the range.
      tion computes the appropriate DNS domain field.
     −
      NOTE: The return value is aligned to the next available byte boundary,
+
=== ldapBase($domain) ===
      i.e.
     −
            192.168.8.4/255.255.255.0 returns "8.168.192.in-addr.arpa."
+
Given a domain name such as foo.bar.com, generate the LDAP base name "dc=foo,dc=bar,dc=com".
            192.168.8.4/255.255.252.0 returns "168.192.in-addr.arpa."
+
 
            192.168.8.4/255.255.0.0  returns "168.192.in-addr.arpa."
+
=== backgroundCommand($delaySec, @command) ===
            192.168.8.4/255.252.0.0  returns "192.in-addr.arpa."
+
 
            192.168.8.4/255.0.0.0    returns "192.in-addr.arpa."
+
Run command in background after a specified delay.
   −
      This string is suitable for use in BIND configuration files.
+
== PASSWORD UTILITIES ==
 +
Low-level password-changing utilities. These utilities each change passwords for a single underlying password database, for example /etc/passwd, /etc/samba/smbpasswd, etc.
   −
      computeHostRange($ipaddr, $netmask)
+
=== validatePassword($password, $strength) ===
   −
      Given a network specification (IP address and netmask), compute the
+
Validate Unix password.
      total number of hosts in that network, as well as the first and last IP
  −
      addresses in the range.
     −
      ldapBase($domain)
+
=== setUnixPassword($username, $password) ===
   −
      Given a domain name such as foo.bar.com, generate the LDAP base name
+
Set Unix password
      "dc=foo,dc=bar,dc=com".
     −
      backgroundCommand($delaySec, @command)
+
=== authenticateUnixPassword ($username, $password) ===
   −
      Run command in background after a specified delay.
+
Check if the given username/password pair is correct.  Return 1 if they are correct, return 0 otherwise.
   −
PASSWORD UTILITIES
+
=== setUnixPasswordRequirePrevious($username, $oldpassword, $newpassword) ===
      Low-level password-changing utilities. These utilities each change
  −
      passwords for a single underlying password database, for example
  −
      /etc/passwd, /etc/samba/smbpasswd, etc.
     −
      validatePassword($password, $strength)
+
Set Unix password but require previous password for authentication.
   −
      Validate Unix password.
+
=== setSambaPassword($username, $password) ===
   −
      setUnixPassword($username, $password)
+
Set Samba password
   −
      Set Unix password
+
=== cancelSambaPassword($username) ===
   −
      authenticateUnixPassword ($username, $password)
+
Cancel Samba password
   −
      Check if the given username/password pair is correct.  Return 1 if they
+
=== LdapPassword() ===
      are correct, return 0 otherwise.
     −
      setUnixPasswordRequirePrevious($username, $oldpassword, $newpassword)
+
Returns the LDAP password from the file "/etc/openldap/ldap.pw".  If the file does not exist, a suitable password is created, stored in the file, then returned to the caller.
   −
      Set Unix password but require previous password for authentication.
+
Returns undef if the password could not be generated/retrieved.
   −
      setSambaPassword($username, $password)
+
=== set_secret() ===
 +
Shortcut method to create and set a password property on a record without having to extract the record first.
   −
      Set Samba password
+
The password creation is based on an UID of 64 bits (Data::UUID). If the optional type option is passed, it will be used to create the record if it does not already exist. Otherwise, a default 'service’ type will be used to create the record.
   −
      cancelSambaPassword($username)
+
The $DB is expected to be an already open esmith::DB object, so that an open DB in the caller can be re-used.  Therefore in a migrate fragment you could just use $DB.
   −
      Cancel Samba password
+
esmith::util::set_secret($DB, '$key','$property'[,type=>'$type']);
   −
      LdapPassword()
+
For example in /etc/e-smith/db/configuration/migrate/90roundcube
 +
{
 +
esmith::util::set_secret($DB, ’foo’,’DbPassword’,type=>’service’);
 +
}
   −
      Returns the LDAP password from the file "/etc/openldap/ldap.pw".  If
+
The password will be generated to the property ’DbPassword’ in the ’foo’ key.
      the file does not exist, a suitable password is created, stored in the
  −
      file, then returned to the caller.
     −
      Returns undef if the password could not be generated/retrieved.
+
If you want to change the database then you must open another esmith::DB objet
 +
{
 +
my $database = esmith::ConfigDB->open(’accounts’) or
 +
    die esmith::DB->error;
 +
esmith::util::set_secret($database, ’foo’,’DbPassword’,type=>’user’);
 +
}
   −
HIGH LEVEL PASSWORD UTILITIES
+
The password is generated on an initialize-default-databases action
      High-level password-changing utilities. These utilities each change
+
/etc/e-smith/events/actions/initialize-default-databases
      passwords for a single e-smith entity (system, user or ibay). Each one
  −
      works by calling the appropriate low-level password changing utilities.
     −
      setUnixSystemPassword($password)
+
== HIGH LEVEL PASSWORD UTILITIES ==
 +
High-level password-changing utilities. These utilities each change passwords for a single e-smith entity (system, user or ibay). Each one works by calling the appropriate low-level password changing utilities.
   −
      Set the e-smith system password
+
=== setUnixSystemPassword($password) ===
   −
      setServerSystemPassword($password)
+
Set the e-smith system password
   −
      Set the samba administrator password.
+
=== setServerSystemPassword($password) ===
   −
      setUserPassword($username, $password)
+
Set the samba administrator password.
   −
      Set e-smith user password
+
=== setUserPassword($username, $password) ===
   −
      setUserPasswordRequirePrevious($username, $oldpassword, $newpassword)
+
Set e-smith user password
   −
      Set e-smith user password - require previous password
+
=== setUserPasswordRequirePrevious($username, $oldpassword, $newpassword) ===
   −
      cancelUserPassword
+
Set e-smith user password - require previous password
   −
      Cancel user password. This is called when a user is deleted from the
+
=== cancelUserPassword ===
      system. We assume that the Unix "useradd/userdel" programs are called
  −
      separately. Since "userdel" automatically removes the /etc/passwd
  −
      entry, we only need to worry about the /etc/samba/smbpasswd entry.
     −
      setIbayPassword($ibayname, $password)
+
Cancel user password. This is called when a user is deleted from the system. We assume that the Unix "useradd/userdel" programs are called  separately. Since "userdel" automatically removes the /etc/passwd entry, we only need to worry about the /etc/samba/smbpasswd entry.
   −
      Set ibay password
+
=== setIbayPassword($ibayname, $password) ===
   −
SERVICE MANAGEMENT UTILITIES
+
Set ibay password
      serviceControl()
     −
      Manage services - stop/start/restart/reload/graceful
+
== SERVICE MANAGEMENT UTILITIES ==
 +
=== serviceControl() ===
 +
Manage services - stop/start/restart/reload/graceful
   −
      Returns 1 for success, 0 if something went wrong, fatal exception on
+
Returns 1 for success, 0 if something went wrong, fatal exception on bad arguments.
      bad arguments.
      
           serviceControl(
 
           serviceControl(
Line 224: Line 207:  
           );
 
           );
   −
      EXAMPLE:
+
==== EXAMPLE: ====
    
           serviceControl( NAME=>’httpd-e-smith’, ACTION=>’reload’ );
 
           serviceControl( NAME=>’httpd-e-smith’, ACTION=>’reload’ );
   −
       NOTES:
+
or another example in /etc/e-smith/events/actions/ldap-delete-dumps
 +
 
 +
if($ldap and $ldap->prop('status') eq 'enabled')
 +
  {
 +
    esmith::util::serviceControl(
 +
       NAME => 'ldap',
 +
      ACTION => 'stop',
 +
      BACKGROUND => 'false')
 +
  }
   −
      The BACKGROUND parameter is optional and can be set to true if
+
==== NOTES: ====
      start/stop/restart/etc. is to be done in the background (with back-
  −
      groundCommand()) rather than synchronously.
     −
      CONVENTIONS:
+
The BACKGROUND parameter is optional and can be set to true if start/stop/restart/etc. is to be done in the background (with backgroundCommand()) rather than synchronously.
   −
      This command is the supported method for action scripts, blade han-
+
==== CONVENTIONS: ====
      dlers, etc., to start/stop/restart their services. Currently this is
  −
      done via the rc7 symlinks, but this may change one day. Using this
  −
      function gives us one location to change this behaviour if desired,
  −
      instead of hunting all over every scrap of code. Please use it.
     −
      getLicenses()
+
This command is the supported method for action scripts, blade handlers, etc., to start/stop/restart their services. Currently this is done via the rc7 symlinks, but this may change one day. Using this function gives us one location to change this behaviour if desired, instead of hunting all over every scrap of code. Please use it.
   −
      Return all available licenses
+
=== getLicenses() ===
   −
      In scalar context, returns one string combining all licenses In array
+
Return all available licenses In scalar context, returns one string combining all licenses In array context, returns an array of individual licenses
      context, returns an array of individual licenses
     −
      Optionally takes a language tag to be used for retrieving the licenses,
+
Optionally takes a language tag to be used for retrieving the licenses, defaulting to the locale of the server.
      defaulting to the locale of the server.
     −
initialize_default_databases
+
=== initialize_default_databases ===
 
Initialize all databases located at /etc/e-smith/db.
 
Initialize all databases located at /etc/e-smith/db.
   −
AUTHOR
+
== AUTHOR ==
      Mitel Networks Corp.
+
Mitel Networks Corp.
   −
      For more information, see http://www.e-smith.org/
+
For more information, see http://www.e-smith.org/
 +
[[Category:Developer]]
 +
[[Category:SME Server Development Framework]]
 +
[[Category:Development Tools]]

Navigation menu