Circles of Archimedes

Background

It is often desirable to collect the system logs from various devices onto a central “logging host”.  This can simplify monitoring needs considerably as tools and scripts need only work on a single host.  It also provides some security benefits as hackers will have a harder time masking their activities if they do not have access to the logging host.

On Mac OS X, there is a logging daemon (the Unix standard syslogd utility) that can be used to write both local logs and receive logs from remote hosts.  Unfortunately, the ability to receive remote logs is turned off in the default installation.  However, it is a trivial task to enable this functionality.

Setup

1. Login as administrator to the logging host
2. Open a terminal session using the Terminal utility
3. Navigate to the LaunchDaemons directory
   cd /System/Library/LaunchDaemons
4. Edit the com.apple.syslogd.plist file
   sudo vi com.apple.syslogd.plist
5. Remove the comment delimiters (<!-- and -->) surrounding the NetworkListener block
   

   <!--
    <key>NetworkListener</key>
    <dict>
    <key>SockServiceName</key>
    <string>syslog</string>
    <key>SockType</key>
    <string>dgram</string>
    </dict>
   -->

6. Stop the currently running instance of the syslog daemon
   sudo launchctl unload /System/Library/LaunchDaemons/com.apple.syslogd.plist
7. Restart the syslog daemon to pick up the changes in the LaunchDaemon configuration
   sudo launchctl load /System/Library/LaunchDaemons/com.apple.syslogd.plist

The logging facility on the log host should now be available for remote devices to use.

Background

PHP is a very popular language for web development.  Providing bindings for directly calling rrdtool within PHP provides a simple and efficient means of providing a high-level scripting interface into the data management and display capabilities of rrdtool.  The stock installation of rrdtool does not provide any support for PHP so bindings must be created for it manually.

Setup

1. Download the php_rrdtool archive from the contributions directory of the RRDTool site.
2. Extract the archive contents into the /usr/include/php/ext directory.

   sudo tar xzvf php_rrdtool.tar.gz -C /usr/include/php/ext

3. Change the owner and group to “root” and “wheel”.

   sudo chown -R root:wheel /usr/include/php/ext/rrdtool

4. Navigate to the newly created rrdtool directory.

   cd /usr/include/php/ext/rrdtool

5. Generate the configuration files for the PHP bindings.

   sudo phpize

6. Execute the newly-generated configuration script for the PHP bindings.  Note that the --with-rrdtool argument takes as its value the “root” directory where the various rrdtool files are located.  If installed using the default values supplied by the MacPorts utility, the “root” directory would be /opt/local.

   sudo ./configure CFLAGS="-fnested-functions" --with-php-config=/usr/bin/php-config --with-rrdtool=/opt/local

7. Make the php rrdtool extension.

   sudo make

8. Install the php rrdtool extension.  Make a note of the directory into which the extension was deployed.

   sudo make install

9. Make a backup copy of the /etc/php.ini file for safety.  If the file does not yet exist, then copy the /etc/php.ini.default instead.

   sudo cp php.ini php.ini.orig

   or

   sudo cp php.ini.default php.ini

10. Edit the /etc/php.ini file and alter the value of the extension_dir variable to the deployment directory (noted in Step 8).

    extension_dir = "/usr/lib/php/extensions/no-debug-non-zts-20060613/"

11. Edit the /etc/php.ini file and a new variable under the Dynamic Extensions section specifying the rrdtool extension.

    extension=rrdtool.so

12. Restart the apache server to load the new configuration information.

    sudo apachectl restart

13. Verify the rrdtool extension can be loaded from within PHP.

    php -m

Special Notice for Mac OS X Users

With the evolution from 32-bit to 64-bit architectures in progress, it may arise that the rrdtool module is accessible through some mechanisms and not through others.  For example, it has been observed on some hardware/operating systems that the module will load properly when referenced directly by the PHP interpreter (i.e. php -m), but is not accessible when referenced within a web page served by Apache (i.e. not listed as part of the phpinfo() output).  This situation is most likely due to Apache running in 64-bit mode while the PHP interpreter and associated extensions are running in 32-bit mode.  If  this situation arises, then the suggested solution is to force Apache to run in 32-bit mode.

Background

With the evolution of Apple’s hardware from 32-bit to 64-bit compatibility, there are bound to be some difficulties.  They have tried to alleviate much of the complexity of running in this environment through their use of universal binaries, but sometimes there are unforeseen difficulties that require “undoing” some of Apple’s handiwork.

As an example, the standard Apache web server is actually made of 4 different executables:  32-bit and 64-bit versions for the PowerPC architecture, and 32-bit and 64-bit versions for the Intel (x86) architecture.  Normally, the operating system runs the “most appropriate” version depending on the nature of the hardware.  However, this may cause problems when trying to use Apache modules which may not support the “most appropriate” version.  A common occurrence of this is when using the PHP module and some of its extensions.

There are two possible methods of alleviating this problem:  recompile every module and extension so that it is in the supported architecture or strip the 64-bit binary from the Apache universal binary which forces the operating system to run it in 32-bit mode.  As the more expedient solution is simply to force Apache into 32-bit mode, that is the route explained below.

Special Notice

This procedure alters the installed Apache web server.  The changed binary may be over-written by a future update which may require this procedure to be repeated.  This procedure has been tested only on Leopard running on an Intel-based Mac Pro.  Older PowerPC-based systems or systems running Snow Leopard may not require this process.

Setup

1. List the supported architectures in the Apache binary.

   file /usr/sbin/httpd

2. Verify that “Mach-O 64-bit executable x86_64″ is listed as part of the universal binary.
3. Copy the original executable to a backup location for safety.

   sudo cp /usr/sbin/httpd /usr/sbin/httpd.orig

4. Stop the web server.

   sudo apachectl stop

5. Remove the 64-bit executable from the Apache universal binary.

   sudo lipo /usr/sbin/httpd -remove x86_64 -output /usr/sbin/httpd

6. List the supported architectures now in the Apache binary.

   file /usr/sbin/httpd

7. Verify the “Mach-O 64-bit executable x86_64″ is no longer listed as part of the universal binary.
8. Restart the web server.

   sudo apachectl start

Background

The ReadyNAS appliance can advertise the services available on their system through the Bonjour or UPnP protocols.  These service discovery protocols can greatly simplify the client connection and configuration problems.  The web administration interface provides an easy method of controlling some of the services advertised, but there may be additional services running on the ReadyNAS that do not have an administrative interface for controlling their advertisement.

Because the ReadyNAS uses the open-source project avahi to handle service discovery, documentation on extending the list of services to be advertised is readily available.  With this information, it is relatively easy to create new service records for additional services and simplify the user experience.

Setup

In order to create additional avahi service records, it is necessary to enable root SSH access to the ReadyNAS system.

The service file is a simple XML file which defines a service-group record.  The service-group record contains a number of elements which may vary according to the service being advertised.  The two essential elements are the name record, which defines the displayed name for the service in question, and the service record, which defines the type, port, and any other connection-related information.

The name element has one possible attribute – replace-wildcards – which can take a value of “yes” or “no”.  If the attribute is present and the value is “yes”, then a %h can be used in the value which will be automatically substituted with the host name of the system.

The service element groups together the necessary information for service connectivity.  The two most essential elements it contains are the type element and the port element.  The type is the is the official service type as defined by RFC 2782 and the port is simply the listening port number.

Depending on the service, there may be additional elements or attributes that are necessary to have a properly formatted service file.  Be sure to consult the documentation to ensure the service is properly defined before making any changes.

Example

The following is an example configuration that enables service discovery for SSH:


<?xml version="1.0" standalone='no'?>
<service-group>
<name replace-wildcards="yes">SSH on %h</name>
<service>
<type>_ssh._tcp</type>
<port>22</port>
</service>
</service-group>

To activate this service, perform the following actions:

1. Login (via ssh) as “root” to the ReadyNAS appliance.
2. Navigate to the configuration directory.

   cd /etc/avahi/services

3. Create a new file named ssh.service containing the configuration information listed above.
4. Restart the avahi service to load the new service file.

   kill -SIGHUP `ps ax | grep avahi | grep -v grep | awk '{ print $1 }'`

Background

Bugzilla is a very popular open-source issue tracking system.  However, setting up all the user accounts can be a tedious chore, particularly for large user bases.  In addition, there are additional user-management headaches associated with maintaining another list of user names, password issues, and access changes due to staff turnover.

Fortunately, Bugzilla is capable of integrating with the RADIUS service available on the Mac OS X Server.  RADIUS is a remote authentication and authorization service which can handle the user authentication requests for Bugzilla and permit users to simply sign on with their standard account name and passwords.  This relieves the administrator from having to create and maintain another set of accounts and allows the users to simply use their standard account name and password.

It should be noted that the implementation of the RADIUS service on the Mac OS X Server is the open-source FreeRADIUS.  More configuration information and usage can be found on the projects web site.

Prior installation of Bugzilla is assumed for these directions.

Enabling the RADIUS Service

If the RADIUS service has not been enabled on the server, then it is necessary to activate it.  Do not start the service during this step.

1. Open the Server Admin application and connect to the server hosting the RADIUS service.
2. Select the server in the “Servers” pane and then click on the “Settings” icon.
3. Click on the “Services” tab and enable the “RADIUS” service by clicking on the appropriate checkbox.
4. Save the new configuration by clicking on the “Save” button.
5. Select the “RADIUS” service now available in the “Servers” pane.
6. Select the “Settings” icon and select a security certificate to use for the service.  A self-signed certificate can easily be created using the “Manage Certificates” option in the drop-down menu.  Regardless, the certificate used for this service should not have a Private Key Passphrase set.
7. Save the new configuration by clicking on the “Save” button.

Configuring the RADIUS service

The stock RADIUS service on Mac OS X (Leopard) has been configured to work only with Apple’s Airport and Airport Express WiFi systems.  In order to extend its functionality to provide service to other types of systems,  the configuration file must be edited and a special entry must be created.

1. Open the Server Admin application and connect to the server hosting the RADIUS service.
2. Select the RADIUS service for configuration.  If the service is already running, then click on the “Stop RADIUS” button to stop it.
3. Click on the “Base Stations” icon and then the “Add…” button to create a new entry.  The most important elements to set correctly are the Type and IP Address.  Type must be “other” and the IP Address should be the address of the Bugzilla server.
   

   Name: Bugzilla
   Type: other
   IP Address: 192.168.1.2
   Shared Secret: ********
   Verify: ********

4. Make a backup copy of the /etc/raddb/users configuration file for safety.

   sudo cp /etc/raddb/users /etc/raddb/users.orig

5. Edit the /etc/raddb/users configuration file to alter the default authentication type to use the Open Directory service instead of the local account database.  The line in question should be approximately 153 lines down in the file (as of 10.5.8).

   Replace: DEFAULT Auth-Type = System
   with: DEFAULT Auth-Type = opendirectory

6. Return to the Server Admin application and start the RADIUS service.

Testing the RADIUS service

In order to verify the RADIUS service is working properly it should be tested using the included test tool radtest.  The general format for testing the RADIUS service is:

radtest user password radius-server nas-port-number shared-secret

user is the username to be tested.

password is the user’s password.  Note that this is given in cleartext and so may be considered a security risk.  It is suggested that you change the password immediately after concluding the test.

radius-server is the hostname (or IP address) of the server hosting the RADIUS service.

nas-port-number is the value of the NAS-Port attribute.  For testing purposes, it does not matter what value is provided as long as it is between 0 and 2^31.

shared-secret is the shared secret established when the service was configured.

The following is an example usage showing the result of a successful test:

$ radtest groucho RufusTFirefly radius.example.com 10 SecretWord
Sending Access-Request of id 203 to 192.168.1.2 port 1812
User-Name = "groucho"
User-Password = "RufusTFirefly"
NAS-IP-Address = 255.255.255.255
NAS-Port = 10
rad_recv: Access-Accept packet from host 192.168.1.2:1812, id=203, length=20

Configuring Bugzilla for RADIUS authentication

RADIUS configuration requires administrative access to the Bugzilla installation.  It cannot be performed as a “normal” user of the system.  It is best practice to verify the RADIUS service is working properly before attempting to configure a dependent service.

1. Install the Authen::Radius perl module (if not already installed as part of the initial setup).

   sudo cpan -i Authen::Radius

2. Login as administrator to Bugzilla.
3. Click on the “Administration” link.
4. Click on the “Parameters” link.
5. Click on the “RADIUS” link
6. Fill in the information for all the RADIUS fields.  The server is the hostname where the RADIUS service is running.  The secret it the shared secret established when the service was configured.  The NAS IP is the address where the Bugzilla service is running.  The email suffix is appended to the username to generate the appropriate email address for each user.
   

   RADIUS_server:  radius.example.com
   RADIUS_secret:  ********
   RADIUS_NAS_IP:  192.168.1.2
   RADIUS_email_suffix:  @example.com

7. Click on the “Save Changes” button to save the new configuration information.
8. Click on the “User Authentication” link.
9. Navigate to the user_verify_class and activate RADIUS as a valid authentication mechanism.  It is strongly suggested that you leave the DB method also activated.
10. Click on the “Save Changes” button to save the new configuration information.

Related Links

• Installing Bugzilla on Mac OS X Server

Background

The ReadyNAS appliance can use the standard service discovery protocols (Bonjour, UPnP) to advertise the services it offers which can greatly simplify client configuration.  While it can easily enable/disable the discovery protocols with the web administration interface, it does not provide a means of customizing the service names.

Because ReadyNAS is based on the Linux operating system, it is able to use the open source solution avahi to handle the service discovery.  This service can easily be configured to display alternate names.

Setup

The ReadyNAS system uses a stock template for each service it is able to advertise.  When activated, the appropriate template is processed into a service record which is used by the avahi daemon to advertise the various services.  In order to effect a persistent change, the template itself must be modified with the desired service name.  Directly modifying the service record will result in the changes being lost should the template be reprocessed.

The template is a simple XML file which defines a service-group record.  The service-group record contains a number of elements which may vary according to the service being advertised.  The only element which is necessary to modify for customizing the displayed name is the <name> element.

The value of the <name> element contains the text of the service advertisement.  If the replace-wildcards="yes" attribute is set, the text may include a %h which will automatically be expanded into the hostname.  If the replace-wildcards attribute is absent or set to “no”, then no hostname expansion will occur.  It is suggested that the names advertise both the hostname and the service in order to avoid confusion.

Here is an example (stock) template for the AFP (Apple Filing Protocol) service:

<?xml version=”1.0″ standalone=’no’?><!–*-nxml-*–>
<service-group>
<name replace-wildcards=”yes”>%h (AFP)</name>
<service>
<type>_afpovertcp._tcp</type>
<port>548</port>
</service>
</service-group>

In order to access the necessary configuration files, the EnableRootSSH patch must first be successfully installed.

1. Disable both the Bonjour and UPnP discovery services using the ReadyNAS web administration interface.
2. Login (via ssh) as “root” to the ReadyNAS appliance.
3. Navigate to the configuration directory.

   cd /etc/avahi/services

4. Make a backup of the original configuration file for safety.

   cp afp.template afp.template.orig

5. Edit the <name> element by replacing the value with the desired text.  If the replace-wildcards="yes" attribute is set, then the hostname will be substituted for a %h in the value text.

   <name replace-wildcards="yes">AFP on %h</name>

6. Re-enable the Bonjour and UPnP discovery services using the ReadyNAS web administration interface.

Background

With a recent upgrade of the ReadyNAS firmware, Infrant (now Netgear) introduced the streaming service “ReadyDLNA”.  This is actually an open source project (”minidlna”) initiated by a Netgear engineer.  This DLNA (”Digital Living Network Alliance”) streaming service is capable of delivering audio, video, and pictures to a number of DLNA-compliant media players.

The ReadyDLNA service works quite well but does not provide a means of specifying multiple media directories in the ReadyNAS web administration interface.  It also does not expose the capability to assign “roles” to the different directories through the web interface.

Setup

In order to access the necessary configuration files, the EnableRootSSH patch must first be successfully installed.  Enhancements to the web interface to permit easier access to these “hidden” configuration options have been promised for future versions, but currently the only means of altering them is through directly editing the configuration files.

To add multiple media directories for the ReadyDLNA service:

1. Login (via ssh) as “root” to the ReadyNAS appliance.
2. Navigate to the configuration directory.

   cd /etc

3. Make a backup of the original configuration file for safety.

   cp minidlna.conf minidlna.conf.orig

4. Edit the minidlna.conf file by creating additional “media_dir” entries with the appropriate path.  For the ReadyNAS appliances, all the data is typically stored on a single volume (“/c”) with the sharepoint name being the next item on the path and then the directory name(s).

   media_dir=/c/media/Music
media_dir=/c/media/Videos
media_dir=/c/media/Pictures
media_dir=/c/torrents/BitTorrent

5. Restart the ReadyDLNA service.  (The easiest way to do this is to simply reboot the ReadyNAS appliance.)

Another “hidden” feature of the minidlna service is the ability to assign roles to the different media directories.  This can help restrict the type of content listed for a particular playback device.  There are three roles that may be assigned:  Audio (“A”), Video (“V”), and Pictures (“P”).  If no role is assigned to a media directory, then all media types will be indexed.

To assign roles to the media directories:

1. Login (via ssh) as “root” to the ReadyNAS appliance.
2. Navigate to the configuration directory.

   cd /etc

3. Make a backup of the original configuration file for safety.

   cp minidlna.conf minidlna.conf.orig

4. Edit the minidlna.conf file “media_dir” entries by specifying the role (“A”, “V”, or “P”) before the path.  The role and path should be comma-delimited.

   media_dir=A,/c/media/Music
media_dir=V,/c/media/Videos
media_dir=P,/c/media/Pictures
media_dir=V,/c/torrents/BitTorrent

5. Restart the ReadyDLNA service.  (The easiest way to do this is to simply reboot the ReadyNAS appliance.)

Background

With a recent upgrade of the ReadyNAS firmware, Infrant (now Netgear) introduced the streaming service “ReadyDLNA”.  This is actually an open source project (“minidlna”) initiated by a Netgear engineer.  This DLNA (“Digital Living Network Alliance”) streaming service is capable of delivering audio, video, and pictures to a number of DLNA-compliant media players.

The ReadyDLNA service works quite well but does not provide a means to alter the displayed service name in the ReadyNAS web administration interface.  In order to customize the service name, it is necessary to update the service’s configuration files directly.

Setup

In order to access the necessary configuration files, the EnableRootSSH patch must first be successfully installed.  Enhancements to the web interface to permit easier access to these “hidden” configuration options have been promised for future versions, but currently the only means of altering them is through directly editing the configuration files.

1. Login (via ssh) as “root” to the ReadyNAS appliance.
2. Navigate to the configuration directory.

   cd /etc

3. Make a backup of the original configuration file for safety.

   cp minidlna.conf minidlna.conf.orig

4. Edit the minidlna.conf file by replacing the value of “friendly_name” with the desired alternate text.  In addition, the variable must be uncommented by removing the leading “#”.

   friendly_name=Movies, Music, and More

5. Restart the ReadyDLNA service.  (The easiest way to do this is to simply reboot the ReadyNAS appliance.)

Background

Infrant (recently purchased by Netgear) makes a number of Network Attached Storage (NAS) appliances that are well suited for home or small business use.  These appliances run a variant of Linux and so are easily enhanced or altered beyond their original configurations.  While the web interface provides a great deal of functionality, there may be a desire for deeper levels of customization than the web interface can provide.  Enabling root access to the system is the first step in exploring these customization opportunities.

Special Note

With root access, it is possible to cause serious damage to both the appliance’s operating system as well as any data stored on the appliance.  Be extra careful when making any changes.  If root access is enabled, Netgear holds the right to deny support!

Setup

There are several types of NAS appliances made by Infrant, but these general guidelines should be applicable to all of them.  They have been tested only on the ReadyNAS NV+ appliance, so other systems may have slight variations.

The ReadyNAS support pages have a list of all available add-on downloads (including some contributed by the community).  As there are several different architectures and operating system versions, please pick the appropriate configuration when downloading the patch.

1. Download the appropriate version of the EnableRootSSH shell access patch.
2. Navigate to your ReadyNAS administrative page and login as administrator.
3. Click the “System” link (in the left-hand navigation area).
4. Click on the “Update” link (under the “System” heading).
5. Click on the “Local” tab to be presented with the option of uploading a locally available patch.
6. Click on the “Browse” button and select the EnableRootSSH file.  It is probably named something along the lines of EnableRootSSH_1.0.bin.
7. Click on the “Upload and Verify” button.
8. After the patch has been uploaded successfully, a dialog should be presented with the option to actually apply the patch.  Click on the “Perform System Update” button to apply the patch.
9. Upon successful application, the system should present a dialog requesting to reboot the system in order to activate the patch.  Reboot the system as directed.
10. When the system has rebooted, root SSH access should be enabled.  The password will initially be the same as that used for the administrative web interface.

Introduction

Many of the postings about using rrdtool reference this example setup.  This example is representative of the type of data frequently gathered as part of routine system monitoring.  It has been designed to facilitate the illustration of the techniques and problems referenced in the other postings and is not necessarily representative of actual system monitoring conditions.  While a more typical usage would probably separate out groups of the statistics into several files, this example collects them all in a single file for the sake of simplicity.

The rrdtool must be installed prior to any attempt to create or load data.  It is readily available as a package for installation for a number of Unix distributions or may be downloaded directly from the developer’s website and built locally.

Creating the RRD

The example RRD creates a file named sysinfo.rrd, a start date of Jan 1, 2009 00:00:00 PST (Unix epoch time 1230796800) and a Primary Data Point (PDP) step value of 300 seconds.  There are a number of different measurements that it retains: the system load, temperature, CPU fan speed, amount of used disk space, rate of change in the use of disk space, and the number of bytes written or read from the disk.  For these measurements, it maintains three Round Robin Archives (RRA):  a RRA with a resolution of 5 minutes spanning 31 days, a RRA with a resolution of 15 minutes for 90 days, and a RRA with a resolution of 1 hour for 365 days.

rrdtool create sysinfo.rrd –start 1230796800 –step 300 \
DS:load:GAUGE:600:0:U \
DS:temperature:GAUGE:600:0:500 \
DS:cpu_fan:GAUGE:600:0:U \
DS:disk_used:GAUGE:600:0:U \
DS:disk_change:DERIVE:600:U:U \
DS:bytes_written:COUNTER:600:0:U \
DS:bytes_read:COUNTER:600:0:U \
RRA:AVERAGE:0.5:1:8928 \
RRA:AVERAGE:0.5:3:8640 \
RRA:AVERAGE:0.5:12:8760

Adding Data

The general format for adding data to the RRD is through the update command.  The general format for adding a set of datapoints for the same time value is as follows:

rrdtool update filename timestamp:DS1[:DS2][:DS3]…

filename is the name of the RRD to be updated.  An update command can update only a single RRD file at a time.

timestamp is the time of the event.  This is typically specified in the standard Unix epoch format (number of seconds elapsed since Jan 1, 1970 UTC), however it may also be represented as “N” (for Now) which will insert the data using the current time value.  An alternate format may also be specified using the formats as accepted by the at command.  (See the manual page for the at command for more details on the time format rrdtool supports.)  If the at format is used, the “@” symbol should be used to separate the timestamp from the data values instead of the “:” character.

DS is the value of the data point(s) that are to be inserted into the RRD for the time specified.  The data points are processed in the same order as the Data Sources were specified when the RRD was created.  If there is no data for a particular DS, then a “U” (for Unknown) should be used instead.  If there is more than one DS to be updated in the RRD, the values should be separated by a “:” character.

An alternate update format is also available which may assign a unique time value for each data point:

rrdtool update filename timestamp:DS1 [timestamp:DS2] [timestamp:DS3]…

Data Generation

The perl script sysinfo-sample.pl is available which will create the RRD as well as populate it with a full year’s worth of data.  The data is randomly generated but should bear enough semblance to real data to help illustrate the concepts.  Also, because it is randomly generated it will result in different results each time it is run.

Please note that this script will automatically overwrite any previous instance of the sysinfo.rrd file in the working directory.

1. Create a directory that will hold the example data and associated files.

   mkdir rrd_example

2. Download the sysinfo-sample.pl file into the newly created directory.
3. Verify the permissions on the perl script are set as executable.

   chmod 0755 sysinfo-sample.pl

4. Execute the perl script and wait for the command prompt to reappear.  (This may take 5-15 minutes depending on the speed of your system.)

   ./sysinfo-sample.pl

Upon completion, a file named sysinfo.rrd should be created in the working directory.  It will be filled with one year’s worth of data starting on Jan 1, 2009.