setRealToEffective()
IPquadToAddr($ip)
IPaddrToQuad($address)
IPaddrToBackwardQuad($address)
ldapBase($domain)
cancelSambaPassword($username)
genLdapPassword()
setUnixSystemPassword($password)
setServerSystemPassword($password)
esmith::util - Utilities for e-smith server and gateway development
This file documents esmith::util
version 1.4.0
use esmith::util;
This module provides general utilities of use to developers of the e-smith server and gateway.
setRealToEffective()
Sets the real UID to the effective UID and the real GID to the effective GID.
The processTemplate function takes as arguments a tied reference to the e-smith configuration file, and the name of the output file to produce. The template is found by prepending a template source path to the filename.
We also allow a parallel template hierarchy /etc/e-smith/templates-custom
which is used in preference to the standard templates in
/etc/e-smith/templates
The templates in /etc/e-smith/templates-custom
are merged with the standard
templates in /etc/e-smith/templates
so only modified/additional fragments
need appear in templates-custom
.
It is possible to override a file based template with a customised directory based template (and vice-versa if you really want to).
Example 1: we have a template /etc/e-smith/templates/etc/hosts
that we want to expand to /etc/hosts
Solution 1a: use the old syntax (passing scalars):
processTemplate(\%conf, '/etc/hosts')
Solution 1b: use the new syntax (passing a hash of named parameters): processTemplate({ CONFREF => \%conf, TEMPLATE_PATH => '/etc/hosts', });
NOTE: this will use the TEMPLATE_EXPAND_QUEUE defaults, and since OUTPUT_FILENAME wasn't specified, TEMPLATE_PATH will be used for output
Example 2: we have a template /etc/e-smith/templates-user/qmail
that we want to expand to /home/e-smith/files/users/$username/.qmail
Solution: must use the new syntax (passing a hash of named parameters):
processTemplate({ CONFREF => \%conf, TEMPLATE_PATH => '/qmail', TEMPLATE_EXPAND_QUEUE => [ '/etc/e-smith/templates-user-custom', '/etc/e-smith/templates-user', ], OUTPUT_PREFIX => '/home/e-smith/files/users/$username', OUTPUT_FILENAME => '/.qmail', UID => $username, GID => $username, PERMS => 0644, });
This routine changes the ownership of a file, automatically converting usernames and groupnames to UIDs and GIDs respectively.
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.
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, 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.
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.
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.
NOTE: This code only handles standard class A, B or C networks.
Given an IP address and netmask, the computeLocalNetworkSpec function computes a valid xxx.xxx.xxx.xxx/yyy.yyy.yyy.yyy specifier.
Given a number of bits of network address, calculate the appropriate netmask.
Given an IP address and netmask, the computeLocalNetworkReversed function 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 "4.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.
Given a network specification (IP address and netmask), and a reference to a networks database, compute the network/netmask entries which are to treated as local access.
There is also an optional access parameter which can further restrict
the values returned. If access
is localhost
, this routine will only
return a single value, equating to access from localhost only.
If called in scalar context, the returned string is suitable for use in /etc/hosts.allow, smb.conf and httpd.conf, for example:
127.0.0.1 192.168.1.1/255.255.255.0
Note: The elements are space separated, which is suitable for use in
hosts.allow, smb.conf and httpd.conf. httpd.conf does not permit
comma separated lists in allow from
directives.
If called in list context, returns the array of network/netmask strings.
Given a service, return the string suitable for /etc/hosts.allow, checking to see if the service is defined, whether it is enabled and whether access is set to public, private, or localhost. For example, one of the following:
# smtpd is not defined in the configuration database # smtpd is disabled in the configuration database smtpd: 127.0.0.1 smtpd: 127.0.0.1 192.168.1.1/255.255.255.0 smtpd: ALL
In array, context, the zeroth element is the tag, and the other elements are the matching network entries
And here's the hosts.allow fragment:
{ my %networks; tie %networks, 'esmith::config', '/home/e-smith/networks';
$OUT = esmith::util::computeHostsAllowSpec( NAME=>'smtpd', SERVICES=>{ smtpd => $smtpd }, NETWORKS=>\%networks, IPADDR=>$LocalIP, NETMASK=>$LocalNetmask ); }
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''.
Run command in background after a specified delay.
Low-level password-changing utilities. These utilities each change passwords for a single underlying password database, for example /etc/passwd, /etc/smbpasswd, etc.
Set Unix password
Set Unix password but require previous password for authentication.
Set Samba password
cancelSambaPassword($username)
Cancel Samba password
genLdapPassword()
Generates a random LDAP password file and stores it in
/etc/openldap/ldap.pw
for later use.
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.
Set e-smith user password
Set e-smith user password - require previous 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/smbpasswd entry.
Set ibay password
serviceControl()
Manage services - enable, disable, stop/start/restart/reload Returns 1 for success, 0 if something went wrong
serviceControl( NAME=>serviceName, ACTION=>enable[d]|disable[d]|delete|start|stop|restart|reload|graceful [ ORDER=>serviceOrdering (required for enable) ] [ BACKGROUND=>true|false (default is true) ] );
EXAMPLE:
serviceControl( NAME=>'smtpfwdd', ACTION=>'enable', ORDER=>81 );
NOTES:
enable and disable both ensure that the Sxx script exists. We enable/disable services as a property of the service. The 'd' at the end of enable/disable is optional to simplify interworking with the services entries.
The BACKGROUND parameter is optional and can be set to false if
start/stop/restart/etc. is to be done synchronously rather than
with backgroundCommand()
BUGS:
$fm is the FormMagick object (so we can use it to call $fm->add_lexicon())
@files is the names of the translation files to add (usually this will be
same name as the script in /etc/e-smith/web/functions that's calling this
routine. For instance, /etc/e-smith/web/functions/emailretrieval would
usually call esmith::util::translate($fm, 'emailretrieval')
e-smith, inc.
For more information, see http://www.e-smith.org/