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.
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.
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...
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.
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.
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.
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…
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.
Transcripts, loadsets and command files
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 contains a list of transcripts (.T)
- Each transcript contains a list of files and their attributes
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.
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.
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.
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.
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.
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.
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
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.
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.
- Radmind first fetches the latest command file and associated transcripts from the server. This has no effect on the system.
- 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.
- Finally Radmind copies and deletes files on the client to match the apply-able transcript. For obvious reasons this change is normally irreversible.
- 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.
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.
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.
- 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.
- 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.
- 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.
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.
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.
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.
Creating Special Transcripts
TODO
Radmind Assistant – Client
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.
Radmind Assistant menu
- About - Display versions of all installed radmind tools.
Preferences
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).
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.
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.
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.
User Management
TODO
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
