5,576
edits
Changes
Jump to navigation
Jump to search
Created page with "NAME esmith::util - Utilities for e-smith server and gateway development VERSION This file documents "esmith::util" version 1.4.0 SYNOPSIS use esmit..."
NAME
esmith::util - Utilities for e-smith server and gateway development
VERSION
This file documents "esmith::util" version 1.4.0
SYNOPSIS
use esmith::util;
DESCRIPTION
This module provides general utilities of use to developers of the
e-smith server and gateway.
GENERAL UTILITIES
setRealToEffective()
Sets the real UID to the effective UID and the real GID to the effec-
tive GID.
processTemplate({ CONFREF => $conf, TEMPLATE_PATH => $path })
Depreacted interface to esmith::templates::processTemplate().
chownfile($user, $group, $file)
This routine changes the ownership of a file, automatically converting
usernames and groupnames to UIDs and GIDs respectively.
determineRelease()
Returns the current release version of the software.
NETWORK ADDRESS TRANSLATION UTILITIES
IPquadToAddr($ip)
Convert IP address from "xxx.xxx.xxx.xxx" notation to a 32-bit integer.
IPaddrToQuad($address)
Convert IP address from a 32-bit integer to "xxx.xxx.xxx.xxx" notation.
IPaddrToBackwardQuad($address)
Convert IP address from a 32-bit integer to reversed
"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) com-
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.
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.".
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.
computeAllLocalNetworkPrefixes ($ipaddress, $netmask)
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.
examples:
- 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".
- 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’ ].
This array is suitable for use in configuration of tools such as
djbdns where other network notations are not supported.
computeLocalNetworkShortSpec($ipaddr, $netmask)
Given an IP address and netmask, the computeLocalNetworkShortSpec func-
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,
this function will return "192.168.8.0/24".
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.
computeLocalNetworkSpec($ipaddr, $netmask)
Given an IP address and netmask, the computeLocalNetworkSpec function
computes a valid xxx.xxx.xxx.xxx/yyy.yyy.yyy.yyy specifier.
computeNetmaskFromBits ($bits)
Given a number of bits of network address, calculate the appropriate
netmask.
computeLocalNetworkReversed($ipaddr, $netmask)
Given an IP address and netmask, the computeLocalNetworkReversed func-
tion computes the appropriate DNS domain field.
NOTE: The return value is aligned to the next available byte boundary,
i.e.
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."
This string is suitable for use in BIND configuration files.
computeHostRange($ipaddr, $netmask)
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.
ldapBase($domain)
Given a domain name such as foo.bar.com, generate the LDAP base name
"dc=foo,dc=bar,dc=com".
backgroundCommand($delaySec, @command)
Run command in background after a specified delay.
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.
validatePassword($password, $strength)
Validate Unix password.
setUnixPassword($username, $password)
Set Unix password
authenticateUnixPassword ($username, $password)
Check if the given username/password pair is correct. Return 1 if they
are correct, return 0 otherwise.
setUnixPasswordRequirePrevious($username, $oldpassword, $newpassword)
Set Unix password but require previous password for authentication.
setSambaPassword($username, $password)
Set Samba password
cancelSambaPassword($username)
Cancel Samba password
LdapPassword()
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.
Returns undef if the password could not be generated/retrieved.
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.
setUnixSystemPassword($password)
Set the e-smith system password
setServerSystemPassword($password)
Set the samba administrator password.
setUserPassword($username, $password)
Set e-smith user password
setUserPasswordRequirePrevious($username, $oldpassword, $newpassword)
Set e-smith user password - require previous password
cancelUserPassword
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.
setIbayPassword($ibayname, $password)
Set ibay password
SERVICE MANAGEMENT UTILITIES
serviceControl()
Manage services - stop/start/restart/reload/graceful
Returns 1 for success, 0 if something went wrong, fatal exception on
bad arguments.
serviceControl(
NAME=>serviceName,
ACTION=>start│stop│restart│reload│graceful
[ BACKGROUND=>true│false (default is false) ]
);
EXAMPLE:
serviceControl( NAME=>’httpd-e-smith’, ACTION=>’reload’ );
NOTES:
The BACKGROUND parameter is optional and can be set to true if
start/stop/restart/etc. is to be done in the background (with back-
groundCommand()) rather than synchronously.
CONVENTIONS:
This command is the supported method for action scripts, blade han-
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()
Return all available licenses
In scalar context, returns one string combining all licenses In array
context, returns an array of individual licenses
Optionally takes a language tag to be used for retrieving the licenses,
defaulting to the locale of the server.
initialize_default_databases
Initialize all databases located at /etc/e-smith/db.
AUTHOR
Mitel Networks Corp.
For more information, see http://www.e-smith.org/
esmith::util - Utilities for e-smith server and gateway development
VERSION
This file documents "esmith::util" version 1.4.0
SYNOPSIS
use esmith::util;
DESCRIPTION
This module provides general utilities of use to developers of the
e-smith server and gateway.
GENERAL UTILITIES
setRealToEffective()
Sets the real UID to the effective UID and the real GID to the effec-
tive GID.
processTemplate({ CONFREF => $conf, TEMPLATE_PATH => $path })
Depreacted interface to esmith::templates::processTemplate().
chownfile($user, $group, $file)
This routine changes the ownership of a file, automatically converting
usernames and groupnames to UIDs and GIDs respectively.
determineRelease()
Returns the current release version of the software.
NETWORK ADDRESS TRANSLATION UTILITIES
IPquadToAddr($ip)
Convert IP address from "xxx.xxx.xxx.xxx" notation to a 32-bit integer.
IPaddrToQuad($address)
Convert IP address from a 32-bit integer to "xxx.xxx.xxx.xxx" notation.
IPaddrToBackwardQuad($address)
Convert IP address from a 32-bit integer to reversed
"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) com-
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.
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.".
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.
computeAllLocalNetworkPrefixes ($ipaddress, $netmask)
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.
examples:
- 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".
- 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’ ].
This array is suitable for use in configuration of tools such as
djbdns where other network notations are not supported.
computeLocalNetworkShortSpec($ipaddr, $netmask)
Given an IP address and netmask, the computeLocalNetworkShortSpec func-
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,
this function will return "192.168.8.0/24".
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.
computeLocalNetworkSpec($ipaddr, $netmask)
Given an IP address and netmask, the computeLocalNetworkSpec function
computes a valid xxx.xxx.xxx.xxx/yyy.yyy.yyy.yyy specifier.
computeNetmaskFromBits ($bits)
Given a number of bits of network address, calculate the appropriate
netmask.
computeLocalNetworkReversed($ipaddr, $netmask)
Given an IP address and netmask, the computeLocalNetworkReversed func-
tion computes the appropriate DNS domain field.
NOTE: The return value is aligned to the next available byte boundary,
i.e.
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."
This string is suitable for use in BIND configuration files.
computeHostRange($ipaddr, $netmask)
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.
ldapBase($domain)
Given a domain name such as foo.bar.com, generate the LDAP base name
"dc=foo,dc=bar,dc=com".
backgroundCommand($delaySec, @command)
Run command in background after a specified delay.
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.
validatePassword($password, $strength)
Validate Unix password.
setUnixPassword($username, $password)
Set Unix password
authenticateUnixPassword ($username, $password)
Check if the given username/password pair is correct. Return 1 if they
are correct, return 0 otherwise.
setUnixPasswordRequirePrevious($username, $oldpassword, $newpassword)
Set Unix password but require previous password for authentication.
setSambaPassword($username, $password)
Set Samba password
cancelSambaPassword($username)
Cancel Samba password
LdapPassword()
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.
Returns undef if the password could not be generated/retrieved.
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.
setUnixSystemPassword($password)
Set the e-smith system password
setServerSystemPassword($password)
Set the samba administrator password.
setUserPassword($username, $password)
Set e-smith user password
setUserPasswordRequirePrevious($username, $oldpassword, $newpassword)
Set e-smith user password - require previous password
cancelUserPassword
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.
setIbayPassword($ibayname, $password)
Set ibay password
SERVICE MANAGEMENT UTILITIES
serviceControl()
Manage services - stop/start/restart/reload/graceful
Returns 1 for success, 0 if something went wrong, fatal exception on
bad arguments.
serviceControl(
NAME=>serviceName,
ACTION=>start│stop│restart│reload│graceful
[ BACKGROUND=>true│false (default is false) ]
);
EXAMPLE:
serviceControl( NAME=>’httpd-e-smith’, ACTION=>’reload’ );
NOTES:
The BACKGROUND parameter is optional and can be set to true if
start/stop/restart/etc. is to be done in the background (with back-
groundCommand()) rather than synchronously.
CONVENTIONS:
This command is the supported method for action scripts, blade han-
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()
Return all available licenses
In scalar context, returns one string combining all licenses In array
context, returns an array of individual licenses
Optionally takes a language tag to be used for retrieving the licenses,
defaulting to the locale of the server.
initialize_default_databases
Initialize all databases located at /etc/e-smith/db.
AUTHOR
Mitel Networks Corp.
For more information, see http://www.e-smith.org/