Installation

Installation

Preparation

Before proceeding, first ensure sure that all the listed components have been installed according to site policy, and that they are working correctly. Starfish will install reliably and securely only if these components are reliably and securely installed.

Installation Strategy

Install Starfish consistent with other system software governed by your site policy. Each site has unique requirements, and thus we respect that the installation defaults supplied in the Starfish distribution can only be illustrative. However, since Starfish typically controls multiple systems, consistent installation is very important.

The easiest way to ensure consistency across a site is to maintain a single distribution directory which can be tailored to meet the requirements of all the target systems. If, due to platform variations, a single directory is infeasable, it still makes sense to maintain a single master distribution which can be passed to the target systems at installation time.

Unpacking the distribution file into its directory is straightforward:
gzip -dc file | tar xfo -
The directory must of course be fully secure at all times. After unpacking, verify that file properties are set correctly. File permissions are sufficient as shipped, but file owner and group properties may need to be changed to suit your environment.

The Makefile

The makefile in the toplevel directory contains all the parameters necessary to identify where Starfish should be installed, and where to find its supporting components. You will probably need to modify this file to suit conditions at your site. In a complex environment with many different target systems, you may find it useful to test for system characteristics within the makefile. In any case, the following parameters are likely to need attention:

Name Default Value Description

INSTDIR /usr/local/pkg/$(TARGET) Directory where you intend to install Starfish.

TCLLIB /usr/local/pkg/tcl/lib Installation directory used by Tcl/Tk packages.

Once the makefile is satisfactorily configured, a complete install can be performed using:
make install

The Launch Script

A sample launch script is supplied with the distribution in etc/etc/init.d/starfish. You will install a launch script, agent software, and agent certificates on each system which is to be managed by Starfish.

Name Default Value Description

USER nobody User with suitable privileges for controlling the managed system. Likely to be root at most sites, but will have different values if the site uses some form of role-based access control.

CONF /usr/local/pkg/starfish/etc/starfishrc The configuration file used by the agent.

The Configuration File

A sample configuration file is supplied with the distribution in etc/starfishrc. You will create modified copies of this file for use by each Starfish manager and agent that will be operated at your site. The manager by default looks for its configuration file in $HOME/.starfishrc. The agent is given its configuration file by the launch script. Some configuration values which may need to be changed at your site:

Name Default Value Description

tlsport starfish Name of the network service or port used for communication.

tlsdir /usr/local/pkg/starfish/lib/tls The directory used to store TLS certificates.

tlscafile cacert.pem The Certificate Authority file used to verify certificates.

tlscertfile agentcert.pem The public component of the session certificate to be used. Example only. Actual value will depend on the certificates generated at your site, and will probably be different for managers and agents.

tlskeyfile agentkey.pem The private component of the session certificate to be used. Example only. Actual value will depend on the certificates generated at your site, and will probably be different for managers and agents.

logfacility auth The logging facility used by the agent.

logpriority info The logging priority used by the agent.

Final Installation

The remaining installation steps vary from one site to another. Depending on site conditions, you may be able to automate them through appropriate changes to the makefile.

For the sake of simplicity, the makefile installs both the Starfish manager and agent. Strictly speaking, it's only necessary to install the manager on the few systems which you will use for control. Similarly, only the agent needs to be installed on the managed systems.

Set file owner, group, and permissions to permit appropriate use by the Starfish managers and agents. All configuration files, scripts, and certificates are secure by default meaning that they are shipped with restrictive permissions. You will almost certainly need to relax these restrictions in order to usefully operate the Starfish manager and agents. Plan this step carefully, and make a record of your reasoning as an aid to development of site policy.

Further steps are described in the Configuration section.

Security Considerations

Starfish is secure by default which means that one of your tasks during installation is to relax its security restrictions, and those of your site, to exactly the point where Starfish can be installed and effective, but no further.

The Starfish agent runs by default as user nobody. File ownerships and permissions are restrictive. Default certificates are not supplied with the Starfish distribution. The various configuration options for the agent and manager are set to disable all but core capabilities. No passphrases are stored in the default configuration file.

The supplied ntping program can be used to efficiently generate ICMP echo messages for connectivity testing over groups of hosts. When invoked by the Starfish manager, its used of the ICMP protocol requires it to be run setuid root. By default, it is installed with ordinary ownership and permissions.

Keep in mind that no software can be be more secure than its environment. Your ability to install and configure Starfish on a given system is proof of this. Therefore it's a good strategy to pay close attention to hardening the system which will be used to hold the Starfish distribution, and next to hardening the systems on which the Starfish manager is to be installed. These relatively few systems then provide the leverage to improve security sitewide.

The Starfish manager, along with its configuration file and certificates, is associated with the authority exercised by system administration staff. Site administrators should understand, however, that the manager will exercise the privilege of the agents running on each of the managed systems.

The Starfish manager itself has no authority over the agents beyond that conferred by the certificate which it presents to them. Technically, it is the certificate which carries the authority. Nor can the manager raise the privilege of the agent, no matter what authority it presents.

The security of a manager certificate lies in the private key which is used to authenticate it. If the key is improperly secured, an enemy could use the certificate to launch an attack through the Starfish agents. A key should be made readable only to its owner, and it should be generated with a protective passphrase, recognizing that the passphrase is necessarily less strong than the key itself. A direct attack on the key depends on overcoming both of these factors.

A private key attack might also be made through the Starfish manager if its environment were not properly secured. Even though it has no authority of its own, it must exercise the key during its authentication handshake with the agent, and at this point it must apply a passphrase obtained from the user. If the manager, or something in its environment, were modified so as to capture this passphrase on behalf of an enemy, a brute force attack on the key would not be necessary.

In summary, certificate management has great value for transferring authority between systems, but is not an effective substitute for system security. The Starfish manager, along with its environment, have high value to an attacker and therefore deserve special attention. While Starfish agents may be run on all systems, the manager should be run on hardened systems only.

Name	Default Value	Description
`INSTDIR`	`/usr/local/pkg/$(TARGET)`	Directory where you intend to install Starfish.
`TCLLIB`	`/usr/local/pkg/tcl/lib`	Installation directory used by Tcl/Tk packages.