Radmind Manual for Mac OS X

From radmind

A special thanks goes to Ofir Gal for writing this document and his continued support of the Radmind project.

[edit] The basic idea

Radmind (remote administration daemon) is a client management system that allows you to create a specific setup on a single Mac OS X system and then be able to implement the same setup on multiple clients. Most importantly, Radmind enables you to install updates and new apps on a single Mac and then force the other Macs to inherit the same configuration. It can be set to automatically bring back systems to a pristine state every night in a college lab or as a way to distribute new system updates on demand.

Radmind supports multiple configurations so one Radmind server can handle several departments in your organization, each with its own setup and applications.

The “master” client is used to upload the base OS and any additional applications, drivers and updates to the server. Choose your most recent Apple hardware for this.

Any client can then become the master by simply initiating a radmind update. You can therefore use any up-to-date radmind client to create new loadsets.

At its core, Radmind operates as a tripwire; it is able to detect differences between the server and the client to any managed file system object, e.g. files, directories, links, etc. However, Radmind goes further than just integrity checking: once a difference is detected, Radmind can optionally take action.

This is ideal for small to large businesses as well as schools and universities. Radmind not only lets you upgrade and keep all systems the same, it also lets you downgrade if you need to. Radmind is generally useful if you have three or more Macs that need to run similar or identical configurations.

You can use Radmind to combat any application or system corruption and even deliberate mis- configuration by simply running the Radmind update session. When used with checksums, Radmind also verifies the integrity of files and any damaged ones are replaced.

Radmind even works in super user mode (Command+S at startup) allowing a system administrator to repair a system that won't start properly.

Radmind can be used in conjunction with Apple Software Restore (ASR), NetBoot, NetInstall and Carbon Copy Cloner.

Radmind is a very powerful tool that can also delete important files. It is therefore recommended that you read this document through and only then attempt to use Radmind. It is also a good idea to experiment on test systems before deploying the setup in the real world (if such a thing exists). OS X, unlike its predecessors, installs a large number of files, and you'll want to choose which to manage in the process of your testing.

Radmind does not require a special "master" client for generating updates for other clients; any Radmind client can become the master by simply updating it with Radmind.

Radmind can be set to skip user data and other files - that is leave user documents untouched while updating the rest of the system.

Radmind can be started manually, or automated to run at startup, login, logout or at timed intervals. But before you get ahead of yourself, let's start with the basics...

[edit] Getting Started

Download and install Radmind on two computers – one will be the server, the other will be the client. It is highly recommended that any data on the clients is backed up. It’s very easy to delete users’ data with Radmind.

[edit] Setting up the server

On the server open Radmind Assistant and select Run Setup Steps from the Session menu. In the First Time Run window select I’m new and I want to setup a Radmind server.

Follow the setup procedure and when the setup is complete the Radmind Assistant will close and Open the Server Manager.

[edit] Setting up the client

On the client open Radmind Assistant and select Run Setup Steps. This time select I’m new and I want to setup a managed client.

In the following screens, enter your Radmind server address, leaving the other options at their default values. You can skip the automation options at this point and continue.

The next window lets you select the negative transcript. You can simply select the one that fits your setup best and continue. The Lab Negative transcript is designed for giving you more control over the system while the Desktop Negative transcript gives users more control over their computers, allowing them to install printer drivers for example. Note that the loadset is uploaded as empty files. This is normal for loadsets associated with negative transcripts. The assistant will prompt you to quit all other applications – this is always a good idea.

When the upload is complete go back to the server and open Server Manager. Click Refresh in the Radmind Loadsets window and select to Verify and Check in. You can safely ignore the message that the transcript is incorrect – this refers to the lack of checksums.

Follow the prompts until you end up with a negative transcript assigned to your client

Go back to the client and continue. The next step is to create the base loadset. This can take a few minutes. When the process is complete you will be prompted to upload the base loadset to the server. Depending on your configuration this can take between 20 minutes and several hours. A high speed Ethernet connection and fast Macs at both end can help a lot.

When the upload is complete go back to the server and click Refresh again in the loadsets window. Follow the prompts to add the new loadset to your setup.

[edit] Updating a new client

Assuming you have setup your server successfully you can now move on to update a new client. For this you will need a third Mac. Install Radmind and again open the Radmind Assistant. This time choose the third option – to update the client. When this is complete you should find the new client has inherited the software setup of your first client without affecting any data.

Read on to understand how to customise and get the best out of Radmind…

[edit] How Radmind works

Radmind uses a client-server setup. The server holds all the files required to make a client match a specified configuration. Such a configuration may include OS X and various applications used in your organization.

You can install the server component on any Mac running OSX 10.2 or later, or any UNIX/Linux based systems. It doesn’t have to be an OSX Server. Most main functions of Radmind, including server management, are available via the Radmind Assistant application (Mac OS X only). If you prefer you may also use the Terminal to run Radmind.

Initially, a client is used to create the base setup which is then uploaded to the server. A base setup must have at least one positive and one negative loadsets. The positive loadset contains all the managed files, while the negative is mostly a list of unmanaged items such as the /Users folder. When the setup is verified and saved on the server any other client can be configured to connect to the server and initiate a Radmind update session – effectively downloading and installing all the files required to match the first client. Files and folders in the negative loadset are left alone.

Normal client updates start by downloading the various Radmind server files that describe the required setup for that client. Radmind then scans the client’s file system for any differences between the prescribed setup and the actual files on the client. If any mismatch is found you are then prompted to perform an update which will make the client match the prescribed setup.

In principal, to create a basic working setup you need to install OSX and all your standard applications on one workstation (the source client) and then use Radmind Assistant to upload the setup to the server. Once there, any other client with Radmind installed can initiate an update, which will result in making the new client an identical clone of the source client.

You can then install additional applications on the source client and again upload the changes to the server. The other clients can then be updated to match the new setup.

Whenever Radmind updates a client it deletes any files that were not on the source and copies any missing or modified files from the server. In some ways this works much like folder synchronizers such as psync or rsync. It makes the target identical to the source as defined on the Radmind server, excluding the items contained in the negative loadset.

You use the Server Manager to determine which files end up on the clients. Radmind is able to deliver different files depending on which client is being updated. The server identifies the client by its DNS name or certificate and then send it any combination of software you specify.

In order to skip files and folders that should not be touched with each update such as the Users folder, Radmind uses the negative transcript. Example negative transcripts are included with Radmind and also on the Radmind.org site. These include user files as well as various logs and cache files that should normally be managed differently.

A finely tuned negative transcript is key to a successful Radmind installation and consequent client updates. See the next section to learn more about how it works.

[edit] Transcripts, loadsets and command files

[edit] Overview

Radmind uses three file types to store information about client configuration. These are organised in a hierarchy that allows for a very flexible setup – capable of managing a diverse organisation where each department may require a different setup.

• The Radmind server uses a single configuration file (config) to store a list of clients and their associated command files.
• Each command file (.K) contains a list of transcripts
• Each transcript (.T) contains a list of files and their attributes

[edit] More about the Radmind file hierarchy

Each transcript describes the contents of a loadset which is simply the files & folders required to deploy the transcript. A transcript called MSOffice.T for example, may contain a list of all the files installed by Microsoft Office and the loadset will contain the actual Microsoft Office files and folders.

A command file is used to bring several transcripts and their corresponding Loadsets together. One client may have a command file that includes OS X, Microsoft Office and FileMaker Pro loadsets, while another client could have a command file with the same OSX loadset, scanner drivers and Adobe Photoshop.

You can easily assign each command file you have to many clients using DNS host names and IP address ranges, allowing you to distribute different application sets to different departments for example.

When editing any Radmind files by hand, make sure you use an editor capable of handling very long lines and Unix mode linefeeds. If you use pico remember to use –w option.

[edit] Transcripts (.T)

A transcript is a plain text file containing a list of files with instructions for Radmind. A transcript for a base OS X installation contains 10,000s lines corresponding to each file system object (i.e. files, folders, etc.).

Each line in the transcript lists one system object – a file, folder, link, etc. In addition the privileges settings, the files size and modification date are also listed. The object type is denoted with a single letter where f for example stands for a regular file, d stands for a folder (directory) and h is a hard link. For a full list of object types consult the fsdiff man pages.

You may optionally include checksums to verify the integrity of files, but use of checksums is known to cause unnecessary file copying with the current version of OS X (10.2.x), which optimises some files on the fly. On the other hand, checksums may catch out some viruses and other system hacks.

When updating a client, Radmind compares the state of the clients to the transcripts listed in its command file. It then produces a transcript that describes what changes need to be made to bring the client up-to-date. This temporary transcript is also referred to as apply-able since its contents will be applied to a client.

In an apply-able transcript a + in front of a file name means it is to be copied to the client, while a – indicates that the file will be deleted. If a file appears with no +/- this means that its attributes need changing – most likely its ownership or privileges. If a managed file on a client is different it will be replaced, if it is missing Radmind will copy it to the client. If a file on the client has no match in your transcripts it will be deleted. Similarly, if a file has different privileges these will also be adjusted to match your transcripts.

This means that if a user installed an application or a printer driver they will be deleted by Radmind, but you can use the negative transcript as well as other methods to work around this if needed.

Radmind determines which files should be created, copied, deleted or modified based on your server configuration in where a command file is used to determine which transcripts to employ. The use of multiple transcripts allows greater flexibility and enables you, among other things, to add software and updates to clients quite easily.

Transcripts are normally created on a client and are then uploaded, along with their corresponding files, to the server where they can be made available to other clients.

Most Radmind client updates start by downloading the command file followed by the transcripts it contains to the client. This ensures that the client has an up-to-date version of all configuration files.

Note that the sort order of items in a transcript is crucial for smooth operation of Radmind. The Transcript Editor ensures that your transcripts are properly sorted. If you plan on using a text editor instead, make sure you understand the sort order required.

[edit] Positive Transcripts

Most of your transcripts would be positive. A positive transcript contains a list of file system objects that should be added, modified or deleted. If a file has been modified on the client (this is decided by date, size, privileges and optionally checksums) it would be replaced with the server version of that file.

Most non-user files should normally appear in a positive transcript. This includes the System, Applications, drivers, root Library, etc.

[edit] Negative Transcripts

If you use tools like rsync or Retrospect you will be familiar with the concept of an exclusion list. At first glance it may look like the negative transcript is just that – a list of files and folders that should not be managed. Radmind doesn’t work exactly like any of these tools.

The negative transcript is not an exclusion list!

Instead, Radmind uses the negative transcript to help you maintain a working system on your client and that can mean creating folders and files if they’re missing, or in some cases just tweaking them.

This way Radmind can ensure, for example, that each client has a Users folder in the right place with the correct permissions, but will not touch its contents. In addition to the Users folder, other items such as host name, netinfo database and various cache files would normally be found in a negative transcript.

In most cases, items in the negative transcripts are only managed in the sense that Radmind ensures their existence and attributes, but does not manage their contents, whether the object is a file or a folder. If a file is not found on the client Radmind will copy it across. This is in contrast with positive transcript items that are fully managed and any changes to their contents will trigger a Radmind update.

When creating a new loadset, whether it’s a base load or an overload, Radmind client checks the negative transcript and excludes any items listed from the new loadset.

Normally, you should check the option to store the negative loadset as empty files.

For better understanding of the negative transcript you should read the fsdiff man page, but in most cases understanding the description above will serve you well.

[edit] Special Transcripts

Special transcripts work by assigning a file to a specific computer. You can use certificates, host names or IP addresses to effectively send customised files to a computer. This allows you to get around issues such as license files for applications like Final Cut Pro and FileMaker that use a single file to store a unique hardware specific license file.

While many larger organisations may have a license server or a single license key for all their clients, smaller businesses may not. Special files can help in these cases and also simplify your Radmind server setup.

[edit] Command files (.K)

A command file is a plain text file containing a list of transcripts in an ascending order of priority from top to bottom, with the last item having the highest priority. A command file must contain at least one negative and one positive transcripts. The negative transcript should normally have the highest priority and should therefore be listed last.

You may use one transcript in several command files. This simplifies your setup and reduces your server storage requirements.

If a file appears in more than one transcript, the one lower in the command file takes precedence. This enables you to update clients from iMovie 3.0.1 to 3.0.2 for example, by placing the transcript that contains the 3.0.2 update lower in the command file.

The only exception to this rule is the negative transcript. Items that appear in the negative transcript should in most cases not appear in any of the positive transcripts. Normally Radmind takes care of that, but if you modify the negative transcript, you must also ensure that all active positive transcripts reflect this change.

Using the Server Manager you can assign different command files to specific Macs using their IP address or name to identify them. By default only one host is setup to apply to all clients using the * wildcard. You may use a combination of IP ranges, wildcards and specific addresses to assign different command files to groups of machines. You may have one command file for your music class containing the OS and overloads with music apps, one for graphic design class with graphic tools and another for school staff. The same arrangement equally applies to a business with several departments. For some users a single global host (such as 192.168.1.<1-50>) will suffice, but it should be noted that leaving the wildcard entry means that anyone with access to your server will be able to download any files from the Radmind server so you may want to use a firewall to prevent unauthorised access.

If you want to use more than one command file you must remove the default “*” host or at least make sure it’s listed last.

Your final hosts configuration, which is saved in the server config file, may look something like this:

192.168.0.<1-10>	servers.K
192.168.0.<11-20>	admins.K
192.168.0.<21-100>	staff.K
192.168.1.*	        Music-dept.K
192.168.2.*	        Gfx-dept.K

Each command file in the above example should contain the appropriate transcripts and consequently Radmind will distribute the corresponding files to the different OS X clients in your organisation. You may use the same transcript in more than one command file.

Alternatively you can choose to use certificates to hand out command files. Certificates allow the server to identify the client and serve it the right command file regardless of its IP address. Certificates also increase the security of your Radmind installation.

The various command files are stored on the server and are served to the clients on demand. When a client initiates an update, the Radmind server locates the appropriate command file for that client based on its DNS name, IP address or certificate. In the process the command file is renamed on the client to the default command.K. The client then goes on to retrieve the transcripts listed in the command file if they are out-of-date.

[edit] Nested Command Files

Radmind supports command.K files within others. You could potentially create system.K, musicapps.K, gfxapps.K and similar and then simply combine them to create customised sets for your various groups.

To add a command file into another command file simply drag it from the left pane of the Command File Editor and into the right pane. Putting a command file inside another is the same as putting all its content into the same position.

A staff-laptop.K might then look like this:

system.K
iapps.K
It-utils.K
Laptop-negative.T

system.K might look like this:

Base-1042.T
1045-comb-update.T
Sec-fix-02-06.T

iapps.K might look like this:

iLife06.T
iDVD601-upd.T
iPhoto602-upd.T

it-utils.K might look like this:

ipnetmon.T
devtools.T

The effective staff-laptop.K is shown below:

Base-1042.T
1045-comb-update.T
Sec-fix-02-06.T
iLife06.T
iDVD601-upd.T
iPhoto602-upd.T
ipnetmon.T
devtools.T
Laptop-negative.T

[edit] Loadsets – base loads and overloads

A loadset is a collection of actual files and their corresponding transcript. A base loadset containing a vanilla installation of OS X can be as large as 1.5GB containing 10,000s of files. Loadsets are stored on the Radmind server. A transcript is a text file that describes the contents of the loadset.

A base loadset is the initial loadset that contains a working version of OS X and optionally additional applications.

An overload is a term used to describe all loadsets other than the initial base loadset – i.e. ones that contain additional software and updates.

[edit] What Happens When You Update a Client?

A client update consists of three stages that are reflected in the Radmind Assistant. Each of these requires a user confirmation and only the last one modifies the client.

1. Radmind first fetches the latest command file and associated transcripts from the server. This has no effect on the system.
2. Next Radmind compares the new transcripts to the actual contents of the system and produces a temporary apply-able transcript file containing a list of required changes. This stage also has no effect on the system.
3. Finally Radmind copies and deletes files on the client to match the apply-able transcript. For obvious reasons this change is normally irreversible.
4. In most cases it is a good idea to restart the computer immediately after an update. Whether this is essential or not depends on which files got replaced.

An update profoundly alters the file structure on the client and normally requires a restart. As long as you have correctly configured Radmind and your negative transcript contains the Users folder, no user data will be affected. Nevertheless, having a backup is always highly recommended.

[edit] Update Problems

If an update fails, you should not restart the computer. Instead, try to find what caused the problem. In most cases it is enough to remove the problem item from the apply-able transcript generated when the Radmind Assistant checked the file system for changes to make. To do that restart the Update session, but before applying the actual loadset click on the Review Changes button and remove the offending item from the temporary transcript. Save the transcript and continue the update.

[edit] What Happens When You Create a New Loadset?

New loadsets or overloads are needed when you want to distribute new applications or files to your clients. The best method of doing this is to first update a client using Radmind. This ensures that the overload correctly reflects the required changes.

1. First the client is updated using Radmind. You can now install any new applications, updates, etc and then select Create New Loadset from the Session menu.
2. Radmind next compares the current command file and associated transcripts against the current client configuration and produces a create-able transcript listing the contents of the new loadset you will create. You may review the transcript and possibly remove items you don’t want included in the loadset by clicking the Review Loadset Contents button.
3. Once the transcript is ready it is uploaded along with the corresponding files to the designated server.

A new transcript must always be verified and deployed on the server before it is available to clients.

[edit] Managing Loadsets

It is most likely that the sample negative transcript as well as overloads you create will need editing by hand. As the number overloads and transcripts on your server grow you may also want to merge them to simplify your Radmind setup. This section briefly discusses the options, but for full instructions read the Transcript Editor and Server Manager sections.

[edit] Editing transcripts

In many cases it is necessary to edit transcripts, mostly to remove lines, but in some cases you would also need to add lines to a transcript. Generally it is easier to edit transcripts on the server if you just want to delete the odd line, but if needed you can edit a transcript on a client and then upload it to the server using Radmind Assistant.

The Transcript Editor is a separate application you can use to edit transcripts. Alternatively, you could use a text editor such as BBEdit or vi. Make sure that you save files in Unix compatibility mode (Unix linefeeds). The default transcript editor can be set in the Radmind Assistant preference panel.

On the server, select a loadset in the loadsets window and click Edit to open it in the Transcript Editor. On the server, editing a transcript is normally limited to removing items.

Adding new items to an existing negative transcript is best done on a client. First make sure you have the latest version of the transcripts by running a Radmind update session. Open the transcript you want to edit in /private/var/Radmind/client in the Transcript Editor and drag any files or folders you want added to the editor window. The Transcript Editor will automatically place your files in the correct sort order. Save the transcript when done.

Next you will need to upload the transcript to the server. Select Create New Loadset from the Radmind Assistant Session menu and then skip the first two stages until you get to the Upload Loadset to Radmind Server screen. Select your edited negative transcript and press continue. You will also need to verify and deploy the transcript on the server.

[edit] Creating overloads

With Radmind any client can be used to create an overload. First update the client with Radmind then install the new software. When installation is complete you can use the Radmind Assistant to scan the system for changes and upload those to the server.

Another method can be helpful when you know all where the new software is placed on the system. Many OS X applications like Google Earth or Firefox which are installed by simply copying them to the Applications folder.

If this is the case you may create the overload by opening the Transcript Editor and creating a new transcript. Drag the new folders or applications into the blank transcript window and select Add Directory and Contents in the resulting dialogue box. The Transcript Editor will automatically generate checksums and put the items in the correct sort order. Save the file and use the Assistant to upload the transcript and files to the server.

[edit] Creating Special Transcripts

Creating special transcripts is much like creating a single file positive overlay, except for variations on where files are stored on the server. As creating special transcripts is not fully supported using the Radmind Assistant, this explanation will focus on using the commandline tools. Another excellent tutorial on this topic is available from the University of Utah.

First, on the client machine create a 1 line positive transcript and store it to the server:

fsdiff -1 -c sha1 -o /tmp/file.txt.T ./path/to/special/file.txt 
lcreate -c sha1 /tmp/file.txt.T

Note that the transcript name was explicitly set to the same as the filename, but with an additional '.T' extension. This will be important later for managing privileges.

Now, on the server machine, check the uploaded transcript for correctness:

lcksum -n -c sha1 /var/radmind/tmp/transcript/file.txt.T

Create a special file hierarchy for each certificate/machine/IP which will utilize this special file transcript:

mkdir -p /var/radmind/special/machine1.example.com/path/to/special
mkdir -p /var/radmind/special/machine2.example.com/path/to/special

Copy both the transcript and file into each of these hierarchies. This is required because the special transcripts purpose is for distribution of different files to different clients; clearly the content of file.txt could be changed from the version that was uploaded:

cp /var/radmind/tmp/transcript/file.txt.T /var/radmind/special/machine1.example.com/path/to/special/
cp /var/radmind/tmp/file/file.txt /var/radmind/special/machine1.example.com/path/to/special/

cp /var/radmind/tmp/transcript/file.txt.T /var/radmind/special/machine2.example.com/path/to/special/
cp /var/radmind/tmp/file/file.txt /var/radmind/special/machine2.example.com/path/to/special/

Note that we copied the specially named file.txt.T transcript to be in the same directory so we can manage permissions and ownership on the file.txt file. Without the presence of the specially named file, the special file would get the default permissions and ownership (0444 0 0).

Finally add a special transcript line to the command file shared by machine1 and machine2:

echo "s ./path/to/special/file.txt" | tee -a /var/radmind/command/all_machines.K

Note, location/precedence within the all_machines.K file isn't particularly important as special file always have highest precedence (are last in the file) no matter where they actually show up.

[edit] Radmind Assistant – Client

[edit] Session menu

• Update this machine - This is the default option. Press continue to update the client. Enter IP address or name of server. Skip to continue without downloading latest command file and transcripts. This is useful if you know that you have the latest versions already on the client.

On the next screen you will see whether updates were downloaded or not. Click Continue to compare the client system to the current command file. This may take a while depending on number of installed files, hardware, etc.

The final screen lets you review the apply-able transcript before applying it on the client.

• Create New Radmind Loadset - This menu item starts the creation of a new loadset and uploading it to the server. The first screen reminds you that it’s best to update the client before creating a new loadset. The normal procedure would be to first update the client with Radmind, then install whichever application or updates you want added and then to create the new loadset.

• Open Transcript Editor - Opens the Transcript Editor as defined in the Transcripts section of the Preferences panel.

• Open Server Manager - Opens the Radmind Server Manager.

• Run Setup Steps - Runs through the setup ‘wizard’ as described in chapter 2 – Getting Started.

• Radmind Assistant Log - View the CLI output.

[edit] Radmind Assistant menu

• About - Display versions of all installed radmind tools.

[edit] Preferences

[edit] General

• Radmind Server - The Radmind server the assistant will attempt to communicate with. You can use host names or IP addresses.

• Edit Radmind Server Settings - Here you can manage a list of Radmind server you use and also set the compression level to use with each server.

• Disable & Enable checksums - Radmind Assistant can use checksum to improve the security of the tripwire mechanism. Using checksum Radmind can detect changes to files, even if the file modification date has not changed. This greatly improves its ability to detect system hacks.

On Mac OS X however, checksum differences are triggered far too often to be of great value. Many Mac administrators therefore choose to disable checksums.

• Enable Radmind Update Monitoring - This installs the Radmind Monitor menu item for the current user. This is a small application that runs in the menu bar and regularly checks the Radmind server for updates. If an update is available the menu item changes colour.

• Force removal of file locks - This overrides any file locking on the client, allowing Radmind to delete or modify locked files.

• Ignore errors when uploading - It is common to see some errors when uploading a loadset, as the system still works, moving and changing files ‘under your nose’, mainly when using checksums. This option lets the assistant ignore such errors and continue to upload.

• Always run pre- and post-apply scripts - In many cases it is useful to run scripts before and after a radmind update. Such scripts can be used to totally exclude certain files from radmind management (such as .DS_Store files).

[edit] Security

• SSL Authorization & Encryption - TODO

• Enable user authentication - This option lets you set the user name if your Radmind server is set to require user authentication.

[edit] Transcripts

• Review transcripts with - Select the default transcript editor the Radmind Assistant uses

• Begin Transcript comparison path - The default path used by Radmind Assistant - / for absolute paths and . for relative ones.

• Path comparisons case sensitivity - By default Radmind behaves like most Unix programs – it is case sensitive. Mac OS X however isn’t. You may want to make Radmind behave more like OS X by changing this option.

[edit] Automation

One of Radmind’s most useful features is the ability to automatically run an update session at regular intervals or on logout. This is done using iHook, another excellent tool written by the Radmind team. iHook allows admin level execution of Unix scripts while providing graphical feedback to the user through a standard Mac user interface.

• Run a full Radmind session - Have Radmind update session automatically run daily, weekly or monthly.

• Run on logout - Runs an update session if there are updates on the server when the user logs out.

• Run if user is radmind - Use this as a quick shortcut for updating machines. Create a user called radmind, give it a secure password and enable this option. Radmind will run an update session as soon as the user ‘radmind’ logs in and logout at the end.

• Continue interrupted sessions on reboot - If an automatic radmind session is interrupted it will continue automatically on reboot.

• Download iHook - Click here to download iHook. Please install into /Applications/Utilities.

• Set Configuration - Saves the various scripts and setting files required for Radmind automation.

[edit] User Management

TODO

[edit] Advanced

• Make Preferences Global - This saves the various Radmind preferences into /Library/Preferences making it available for the automation and user management scripts.

• Install Radmind Tools - Install the Unix tools required for running Radmind Assistant

[edit] The Server Manager

The Server Manager is only accessible if your Mac is running the server component of Radmind. Select Server Manager from the Session menu to open the main window.

It is best to be logged in as root when using Radmind Server Manager

The Server Manager consists of three main windows. The Server Configuration Editor, the Command File Editor and the Loadset Manager.

[edit] The Server Configuration Editor

Here you can add clients using host names or ip addresses and assign them a loadset. The server configuration contains the Radmind client list and their associated command files. The host (client) list initially contain just one entry – the * wildcard. This enables any Radmind client to connect to your server for uploads or downloads. Normally, you would want to remove this entry and create a client list using IP addresses or DNS names so that you can control which applications each client gets.

[edit] New Client

Creates a new client entry. You can use host names such as host51.yourdomain.ext or an ip address in the format 192.168.1.5 for single IP addresses, 192.168.1.<51-60> for a range and 192.168.1.* for a complete network. You can also use wildcards in hostnames, like *.music.school.edu.

Next to the client name or IP address is the command file popup menu used to assign a command file to a client. Selecting a client displays its current command file contents on the right window pane. The config file is read in descending order, so you may use wildcards at the bottom of the list to catch all undefined clients.

• Delete - Click the Delete Client button to delete the currently selected client from the list.

• Save - This save the server configuration file that contains the list of clients and their assigned command files. Note that there is only one server configuration file.

• Comment - This button disables a client entry by adding a comment symbol to the server configuration file.

• Refresh Rescans the Radmind configuration files. Use this if you made changes to the file using a text editor to update the display.

[edit] The command file editor

The command files are listed on the left pane, while the contents of the selected command file are shown on the right. Click on command sets to see their contents.

A command file can be edited by adding, removing and re-ordering items or changing their type. You can drag loadsets from the production area of the Loadsets Window into the command file and you may reorder the loadsets at any time by dragging them up and down in the list.

Note that any changes must be saved before they take effect.

• New Command File - Click here to create and new command file. You can create an empty one, or based on an existing command file. The new command file is then available for selection and further editing from the right window pane. You can now add loadsets to the command file by dragging over from the Loadsets Window.

Selection of positive, negative and special transcript type (p, n and s types) is done via the Type popup menu. You can also select the k option to create nested command files.

• Delete - Delete the currently selected command file. This does not delete the transcripts it contains.

• New Folder - You can use folders to organise your command files. These work in the same way as folders work in the Finder.

• Save - Saves the contents of the currently selected command file.

• Add Special Entry - Use this to create hardware specific loadsets. These can be used to manage license files or other machine specific files. ***

• Delete Entry - Removes the currently selected transcript from the command file.

• Refresh - Rescans the Radmind configuration files. Use this if you made changes to the files using a text editor to update the display.

[edit] The Loadsets Window

The Loadsets Window is divided in two – the bottom part displays newly uploaded loadsets while the top half shows the ones ready for deployment.

When a new loadset is uploaded to the Radmind server it is displayed in the bottom half of the Loadsets window. If you cannot see it there press the Refresh button to update the display. A loadset should be verified before adding it to the production area. Verification will fail if the transcript contains no checksums in which case use the Update (recycle) button to generate checksums before you verify. Verified Loadsets can be dragged and dropped into the production area in the top half of the drawer to make them available for deployment.

A loadset is made available to a client by adding it to the client’s command file. Select the command file in the Command File Editor and then drag the loadset from the Loadsets Window into the required position in the command file.

• Verify Loadset - All newly uploaded or edited loadsets should be verified. The verification process ensures that the transcript and files in the loadset match up.

• Update Loadset - This button creates or regenerates transcript checksums. It is useful if your transcript does not contain checksums or if you have manually edited one of the files in the loadset

[edit] Merge

In many cases you may want to merge loadsets to simplify your Radmind installation and reduce storage requirements on the server. You could merge iTunes 6.01 and 6.02 updates for example.

To merge two Loadsets drag one on top of the other.

When merging you can either merge one transcript into another which is quicker, or to produce a third one. The downside of merging in place is that you lose the ability to downgrade. The downside of producing a third transcript is that you also end up with a third loadset which increases your server storage requirements.

You may also need to edit your command files to reflect the merge. An example command file:

p Base10-2-3.T
p 10-2-4update.T
p MSOffice.T
p filemaker6-02.T
p MSOffice10-1update.T
p filemaker6-03update.T
n negative.T

May now look like this:

p Base10-2-4.T
p MSOffice10-1.T
p filemaker6-03.T
n negative.T

• Local Backup - This simply creates a backup of a loadset – a snapshot of it, enabling you to modify the loadset, merge it with others and still roll back to the original state if you need to.

• Log - Display the Radmind server event log.

• Edit - Opens the selected transcript in the Transcript Editor. Normally, only removal of items from a transcript is practical on the server.

• New Folder - You can use folders to organise your loadsets. These work in the same way as folders work in the Finder.

• Delete - Deletes the selected loadset – the transcript and its associated files from the server following a confirmation dialogue.

• Refresh - Causes the Server Manager to rescan the Radmind setup files. This is necessary in order to display newly uploaded loadsets.

[edit] Preferences

[edit] Server

Here you can start and stop the ramdind server and changes its preferences.

• Radmind Directory Path - The default directory that the Radmind server uses is /var/Radmind, use this field to change it. This can be useful if you want to store the Radmind loadsets and other configuration files on a separate disk. Note that changing this option does not move existing loadsets to the new location.

• Port - By default, Radmind uses TCP port 6662, but you can override this value here.

• Maximum Connections - Use this to limit the number of simultaneous clients that the Radmind server will accept.

• Umask - With this option you can control the file permissions the Ramind Server uses. This gives you more control over which users are able to view or modify the Radmind Server settings. A value of 755 for example, means that only the current user can modify files, while others may view them.

• Enable Bonjour - This enables Apple’s network discovery allowing the Radmind Assistant to automatically detect Radmind servers on the local network.

• Compression Level - The maximum compression level the server supports. If the client is set to use compression, the server will compresses all outbound data using the compression level set by client up to the maximum allowed here. Using compression reduces your network traffic, but increases processing time.

• SSL Security Level - TODO

• Require User Authentication for uploads - This option works in combination with the allowed user list below to require user name and password before the Radmind Server will accept uploads.

• Edit Allowed Users - When using SSL, the server can be setup to require user authentication before uploading a loadset. This can prevent someone uploading a huge loadset and filling up the server hard drive. Enter an existing admin user name, the password will be taken from their OS X account info.

[edit] General

• Case Sensitive Transcripts - Mac OS X is not case sensitive while Radmind is by default. When used on Mac OS X you may wish to change it to behave more like OS X and ignore case in file names.

[edit] Advanced

• Define Radmind Right - Used with the timeout value below, this option determines how often Radmind Server will ask for an admin user name and password.

• Timeout - The number of minutes before requiring admin authentication.

[edit] The Transcript Editor

You can use the any text editor, including TextEdit and pico to edit your transcripts. The Transcript Editor is designed to make this a lot easier. The Transcript Editor provides a simple display of the items in the transcript with a few options you can select in the toolbar.

[edit] The Toolbar

• Save - Save changes made to the transcript.

• Convert - You can use this to convert the transcript between relative and absolute paths. Using absolute paths is simpler, but relative paths are more flexible, allowing you to apply a radmind update to non-startup drives.

• Show Info - You can view more info about an item in the transcript by selecting it and clicking the Show Info button.

This reveals information such as owner, kind, size and location. You can click the Edit tab to reveal options you can modify. The editor allows you to overwrite the ownership and permissions of files. This can be useful in some cases, especially when troubleshooting installers that don’t follow the OS X user space model. An unofficial list of such applications is maintained at http://www.macos.utah.edu/documentation/administration/poorly-made_apps.html

• Audit - Get a security report on a transcript. This will list any files that have insecure permissions.

• Toggle Comment - Commenting an item in Radmind is the same as disabling it.

• Delete - Deletes an item from the transcript.

• Search - Use this box to search for items in a transcript. Normally the default path search is all you’ll need. Click on the magnifying glass to reveal more options. You can search by type, owner, groups and more. One of the more useful search modes is the ability to view only items that are about to be added or removed from the system. Wildcard support is optional and can be enabled in the preferences panel.

Path – file name or any part of its path, /Applications for example will display the full contents of the Applications folder.

Type ***
Owner – owner id
Group – group id
Permissions – file permissions represented in octal form
Items to be deleted – perform path search on items to be deleted
Items to be downloaded – perform path search on items to be downloaded

[edit] The Menus

[edit] Preferences

• Base path - This is the default path used when adding new items to a transcript. / means absolute, . is relative.

• Use wildcards in searches - Turn on wildcard support in searches.

• Transcript font size - Select font size for use in main editor display.

[edit] File Menu

• New - Create new empty transcript.

• Open and Open Recent - Open existing transcripts.

• Add Item to Transcript - This is useful when you know the location of files you want to add to a loadset. Many applications are installed by copying them to the applications folder. Such applications can be added to a loadset without having to scan the disk for changes. When prompted select the application or folder you want, then choose to add item and its contents. The Transcript Editor automatically generates checksums and sorts the items.

You can also add an item by dragging it onto an open transcript.

• Show Info - See above – Show Info button in toolbar.

• Show Source Transcripts - This option is useful when debugging your transcripts. It shows you which other transcripts on the client contain the same item. This option does not work on the server.

• Go to line - Quickly navigate using line numbers. This is useful when debugging transcript upload or download errors.

• Toggle Comment - Commenting an item in Radmind is the same as disabling it.

[edit] Edit Menu

• Undo - Undo last action.

• Redo - Redo last action.

• Cut, Copy, Paste, Clear and Select All - The standard OS X clipboard functions are fully supported.

• Advanced Search - Perform searches on current transcript. Similar to standard search but can also ignore case.

[edit] The UNIX tools

Radmind is actually a collection of Unix tools that interact to achieve the complex task of client management. Radmind Assistant merely serves as a front end to these tools and consequently cannot tap into all the possibilities offered by the Unix environment. From time to time you may find it useful to use the Terminal instead of the Assistant to achieve certain tasks. The full up-to-date documents are available in the MAN pages that are installed when you install Radmind.

Most of the tools can be used on both server and client, except Radmind which is the server daemon – a faceless program that serves the Radmind clients. You can verufy that Radmind is running on your server using the Apple Activity Monitor.

All the other tools are run to perform a task and quit. There is no resident, running process called Radmind on the client. Radmind - manual pages

• ktcheck - verify and download command file and transcripts
• fsdiff - compare filesystem to transcripts
• lapply - modify file system to match appliable-transcript
• lcreate - upload transcripts and their corresponding files
• lcksum - verifies a transcript's checksums and file sizes
• lfdiff - compare local files with copies on Radmind server
• lmerge - combines multiple transcripts into one
• Radmind - remote admin daemon
• twhich - locates a file listing in transcripts
• applefile - Radmind AppleSingle file

If the tools won’t run in terminal, add /usr/local/bin/ in front of the tool name.

You can view and edit the various Radmind configuration files in a text editor of your choice. While logged in as root Select Go To Folder… in the Finder and enter /private/var/Radmind to reveal the files. Alternatively, use the Terminal and a text editor like VI (check vilearn for more info).

[edit] Appendix A – Technical Information

[edit] Network and Storage Considerations

Radmind uses port 6662 by default for server-client communication. You may change the port via the command line. If your server is protected by a firewall you will need to open it to allow external access on that port. You may employ SSL encryption and specific IP ranges within Radmind itself to increase your server security.

Radmind also works if the client is behind a NAT/firewall – there is no need to open or re-route any ports on the client side.

You can use the built-in compression in Radmind to reduce your network traffic.

The server is used to store all the loadsets that can build up over time so make sure you have plenty of hard disk space available on the server.

[edit] File Locations

The Radmind executables for both client and server can be found at /usr/local/bin/. Note that under OS X this is not one of the default environment paths. If you don’t want to have to type the full path before each Radmind command enter the following line at the beginning of each Radmind Terminal session:

csh/tcsh: setenv PATH "${PATH}:/usr/local/bin"
sh/bash: PATH="${PATH}:/usr/local/bin"; export PATH

Alternatively add this line to your shell login script. If you’re using bash (the default shell as of OS X 10.4) edit the script which is found in /etc/profile to look something like this:

# System-wide .profile for sh(1)
PATH="/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin"

tcsh users will need to edit /etc/csh.login:

# System-wide .login file for csh(1).
setenv PATH "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin"

To view the man pages for the various tools you need to /usr/local/man to the MANPATH

csh/tcsh: setenv MANPATH "/usr/share/man:/usr/local/man"
sh/bash: MANPATH="/usr/share/man:/usr/local/man"; export MANPATH

These lines can be added to your .cshrc or .profile (or .bashrc).

You could use Radmind to manage this file and ensure that this setup is copied to all your clients.

[edit] On the Server

Radmind stores its various configuration files, transcripts and loadsets in /private/var/Radmind/. On the server the directory includes the following items:

• command/ – all command files are stored here
• transcripts/ – all available production transcripts
• file/ – the actual managed files that make up the various loadsets
• special/ – client specific files
• tmp/file/ – newly uploaded files before they’re moved into production
• tmp/transcripts/ – newly uploaded transcripts

You can relocate the Radmind server files to drives other than the startup disk by using the Server Manager preferences panel or placing a symbolic link to the relocated Radmind directory in /private/var/. Note that on Mac OS X you may also get to this directory using the symbolic link /var. Either way, full root access is required to browse these directories. Use sudo –s in the terminal to obtain full access.

[edit] On the client

The client only keeps one command file which is always called command.K and its associated transcripts. They can all be found at /private/var/Radmind/client.

In addition, temporary items like apply-able transcripts are placed in the /tmp/ directory by Radmind Assistant.

[edit] Appendix B – Incorporating New Hardware

Occasionally, Apple release new models which on first look, have the same version of the OS as the current release. On closer inspection you may find that these new machines ship with a later build of the OS. For example, the Core 2 MacBook Pros were shipped in Nov 2006 with OS X 10.4.8 build 8Nxxx, while previous models that were fully up-to-date only managed to get as far as 10.4.8 build 8Lxxx. Applying your existing Radmind setup to the new hardware is likely to result in problems, because the newer build contains drivers that are needed for the new machine.

You can use Radmind to fish out these drivers and whichever other updated files exist on the new Mac. These can be compiled into a loadset that you can upload to your Radmind server. You can then add this loadset to your existing Radmind setup, effectively merging any any new files in the OS build. Below is a step-by-step guide to get you there:

1. Install base OS on new Mac using Apple CD/DVD

2. Install Radmind

3. Use Radmind Assistant to update the new Mac running only the first step of the process.

4. In Terminal type

  4.1 sudo -s
  4.2 Press Enter
  4.3 /usr/local/bin/fsdiff -A / | grep -v ^- | grep -v ^+ | /usr/local/bin/lapply -h yourserveraddress

5. Press Enter

6. Create loadset on new Mac

  NOTE: Since you're essentially creating a new OS update, it is normal to have tens of thousands of lines in the loadset.

7. Before uploading to the server, search and remove all items with "-" from resulting transcript

8. Upload the above loadset to the radmind server

9. Add loadset as the last positive in the command file

10. You can now update all your Macs, including the new one using Radmind