/ 
esmith-1.70
/ esmith::util

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 effective GID.

processTemplate({ CONFREF => $conf, TEMPLATE_PATH => $path })

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,
});

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) compute 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.

computeLocalNetworkShortSpec($ipaddr, $netmask)

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.

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 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.

computeLocalAccessSpec ($ipaddr, $netmask, %networks [,$access])

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.

computeHostsAllowSpec ( NAME=>serviceName, [ DAEMON=>daemonName, ] SERVICES=>\%services, NETWORKS=>\%networks IPADDR=>ipaddress, NETMASK=>netmask, )

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 );
}

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/smbpasswd, etc.

setUnixPassword($username, $password)

Set Unix password

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/smbpasswd entry.

setIbayPassword($ibayname, $password)

Set ibay password

SERVICE MANAGEMENT UTILITIES

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:

  • We don't currently manage the Kxx scripts - that's up to the package itself

  • The service name must match filename for the rc.d directory

LOCALISATION SERVICES

translate($fm, @files)

$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')

getLicenses()

Return all available licenses

In scalar context, returns one string combining all licenses In array context, returns an array of individual licenses

AUTHOR

e-smith, inc.

For more information, see http://www.e-smith.org/