SunScreen 3.1 Reference Manual

ssadm Subcommands

The following commands, which can be used as the subcommand argument to the ssadm command, are described in this section.

ssadm Subcommand Summary

TABLE B-3 lists the SunScreen ssadm subcommands and their descriptions. Many ssadm subcommands duplicate the functions of the administration graphical user interface, while others provide a context for other subcommands.

Table B-3 Summary of SunScreen ssadm Subcommands

ssadm Subcommand

Description 

activate

Activates a Screen policy. 

active

Lists information about the currently active policy. 

algorithm

Lists algorithms supported by SKIP. 

backup

Writes a SunScreen backup file to standard output. 

debug_level

Sets or clears the level of debugging output generated by a Screen. 

edit

Runs the SunScreen configuration editor. See "Configuration Editor".

ha

Configures the features of a high availability (HA) Screen. 

lock

Examines or removes the protection lock that the configuration editor places on a policy file. 

log

Maintains the Screen log file. 

logdump

Filters or displays log records, as retrieved by ssadm log get.

login

Authenticates a user for administrative access through ssadm to a Screen from a remote Administration Station.

logmacro

Expands a SunScreen logmacro object.

logout

Terminates the session created by ssadm login.

logstats

Prints information about the SunScreen log. 

patch

Installs patch, as needed. 

policy

Creates, deletes, lists and renames Screen policies. 

product

Prints single line of descriptive SunScreen use. 

restore

Reads a backup file from standard input. 

sys_info

Prints a description of running SunScreen software. 

traffic_stats

Reports summary information about the traffic flowing through the SunScreen, classified by interface. 

activate Subcommand

ssadm activate causes the Screen to begin "executing" a particular configuration that is formed when the named policy is combined with the common objects. After activation, the configuration controls the behavior of packet filtering, encryption and decryption, proxies, logging, and administrative access.

Syntax:

ssadm activate [-n] [-l] policy

TABLE B-4 describes the options for this command.

Table B-4 Options for activate Subcommand

Options 

Description  

-n

Does not actually make the configuration active, just verifies that it is valid.  

-l

Does not send the configuration to other Screens in the centralized management group, only activates it on the local Screen.  

The named policy is combined with the common objects to form a configuration.


Note -

If you omit the policy argument, ssadm activate reads a configuration file from standard input. Since the format of a configuration file is undocumented and private to the SunScreen internal software, using ssadm activate in this way is not supported.


active Subcommand

ssadm active prints out a description of the configuration that is currently being executed by the Screen. When run with the -x option, the actual configuration file is extracted from the running system and can be saved for later examination.

Usage:

ssadm active

ssadm active -x policy

Without the -x option, ssadm active describes the active configuration with two lines of text. The first line lists the name of the Screen on which the configuration was originally stored, the name of the internal database in which it was stored (this name is always default), and the name of the policy, including its version number. The second line lists the date and time when the configuration was activated, and the user (either a UNIX user or SunScreen administration authorized user) who caused it to be activated.

For example:


# ssadm active
Active configuration: greatwall default Initial.3
Activated by admin on 03/09/1999 02:58:36 PM PST

In this example, the Screen is currently running a configuration that came from the Screen named greatwall (which might be the current Screen or, if the Screen is a member of a centralized management group, the primary Screen of the centralized administration group). The configuration includes version 3 of the policy Initial.

With the -x option, ssadm active saves the active configuration into the named policy that can be examined using the edit command. The named policy must not already exist; ssadm active creates the policy. The saved policy contains a full set of common objects in addition to the policy rules. The -x option is different from a normal policy that contains only policy rules and is meant to be combined with the currently defined common objects.


Note -

If the -x option is specified and the policy argument is omitted, ssadm active writes a configuration file to standard output. Since the format of a configuration file is undocumented and private to the SunScreen internal software, using ssadm active in this way is not supported.


algorithm Subcommand

ssadm algorithm lists the SKIP algorithms that are available for a specified algorithm type.

Usage:

ssadm algorithm type [skipversion]

where type must be one of "key", "data", "mac", or "compression". skipversion, if supplied, must be either "SKIP_VERSION_1" or "SKIP_VERSION_2".

backup Subcommand

ssadm backup writes a Screen backup file to standard output.

Usage:

ssadm backup [-v] > file

The backup file contains the complete configuration of SKIP, plus all currently defined common objects, policies, and, if the -v option is specified, all of the saved versions of the policies.

The backup file can be restored at a later time using the ssadm restore command.


Caution - Caution -

SECURITY WARNING. The file created by ssadm backup contains sensitive information (SKIP secret keys) that must be stored and disposed of appropriately to protect the integrity of the Screen.


debug_level Subcommand

ssadm debug_level controls the output of internal debugging information from the SunScreen kernel.

Usage:

ssadm debug_level [newlevel]

ssadm debug_level ?

With no arguments, ssadm debug_level prints out the current debug level in hexadecimal. With the newlevel argument, ssadm debug_level sets the debug level to newlevel. With the question mark argument (may need to be quoted in the UNIX shell) ssadm debug_level prints out a list of bit values and their meanings.

The debugging information, when enabled, is written through the kernel message mechanism and typically ends up on the system console or the kernel message logs. The format of the messages is not documented and is only used by Sun support personnel.

edit Subcommand

ssadm edit runs the SunScreen configuration editor.

Usage:

ssadm edit policy

ssadm edit policy < file

ssadm edit policy -c commandstring

See "Configuration Editor" for information regarding commands supported by ssadm edit. The configuration editor can be used in any of three modes: interactive, batch, or "-c" mode. In interactive mode, the editor prints a prompt (edit>) before each command is read from your terminal. In batch mode, the editor silently reads commands from standard input. Commands are read until the editor receives end-of-file or a quit command.

If ssadm edit is run on an interactive terminal and its input and output are not redirected; it automatically enters interactive mode. If standard input is a pipe or a file, the configuration editor runs in batch mode.

If ssadm edit is run with the -c option, it executes the commandstring and then exits without reading any other commands. commandstring must be a single argument to the program, so in the UNIX shell it usually has to be quoted with single or double quotes.

ha Subcommand

ssadm ha performs operations on a Screen in a high availability (HA) cluster.

Usage:

ssadm ha function parameters...

TABLE B-5 describes the function parameters for this command.

Table B-5 Function Parameters for ha Subcommand

Functions 

Descriptions 

status

Displays status of the HA cluster.  

active_mode

Puts the Screen in active mode. 

passive_mode

Puts the Screen in passive mode. 

init_primary interface

Turns a standalone (non-HA) Screen into an HA primary Screen, thereby creating a new HA cluster containing one Screen. interface is the interface to be used for the HA heartbeat and synchronization. primaryIP is the IP address (on the HA network) of the primary machine in the cluster.

init_secondary interface primaryIP

Turns a standalone (non-HA) Screen into an HA secondary screen ready to join an existing HA cluster. Where interface is used for the HA heartbeat and synchronization, and primaryIP is the IP address (on the HA network) of the primary machine in the cluster.

add_secondary secondaryIP

Adds an initialized HA secondary Screen (see init_secondary above) into an existing HA cluster. This command is executed on the primary Screen in the HA cluster. secondaryIP is the IP address (on the HA network) of the secondary machine to be added.

lock Subcommand

ssadm lock manipulates the lock that protects a policy from simultaneous modification by multiple administrators.

Usage:

ssadm lock -w policy

ssadm lock -c policy

ssadm lock -w prints a line of text describing the status of the lock.

ssadm lock -c forcibly breaks the lock and attempts to terminate (with a SIGHUP signal) the previous holder of the lock.

For example:


# ssadm lock -w Initial
Lock held by admin@198.41.0.6 process id:8977
# ssadm lock -c Initial
# ssadm lock -w Initial
Lock available

log Subcommand

ssadm log retrieves and clears the SunScreen log.

Usage:

ssadm log get filter_args...

ssadm log get_and_clear filter_args...

ssadm log clear

logdump Subcommand

ssadm logdump is used to filter or display log records, as retrieved by ssadm log get.

Usage:

ssadm logdump parameters...

login Subcommand

ssadm login authenticates a user for administrative access through ssadm to a Screen from a remote Administration Station.

Usage:

ssadm -r remotehost login username password

ssadm login creates a session on the remote Screen and provides a ticket that allows subsequent invocations of the ssadm command to access the remote Screen without using a password.

ssadm login is only available with the -r remotehost option.

The ticket is written to standard output. If a ticketfile is specified using the -F option to ssadm or the SSADM_TICKET_FILE environment variable, then ssadm login automatically stores the ticket in ticketfile in addition to writing it to standard output.

For example:


# SSADM_TICKET_FILE=$HOME/.ssadmticket
# export SSADM_TICKET_FILE
# touch $SSADM_TICKET_FILE
# chmod go= $SSADM_TICKET_FILE
# chmod go= $SSADM_TICKET_FILE
# ssadm -r greatwall login admin password
WRITE access <E23B344150C702EC>
# ssadm -r greatwall activate Initial
Configuration activated successfully on greatwall.
# ssadm -r greatwall active
Active configuration: greatwall default Initial.3
Activated by admin on 03/09/1999 02:58:36 PM PST
# ssadm -r greatwall logout

The above example is for sh or ksh; other shells may require different commands. ssadm login is only available with the -r remotehost option.

When using the ssadm login command on multiuser Administration Stations, any other user can snoop the admin user and password using ps, then (because SKIP is enabled from that host) access the Screen as that user.

Do not have a general-use Solaris system act as a remote Administration Station. Additionally, never use the ssadm login command on a Solaris system while other users are logged in


Caution - Caution -

Screen administration is discouraged from non-Solaris platforms. Serious security holes with other operating systems can readily be exploited to compromise the network security infrastructure.


See the ssadm-login(1M) man page for more information on the login command.

logout Subcommand

ssadm logout terminates the session created by ssadm login.

Usage:

ssadm -r remotehost logout

ssadm logout is only available with the -r remotehost option.

logmacro Subcommand

ssadm logmacro expands a SunScreen logmacro object.

Usage:

ssadm logmacro expand macroname

logmacro add macrokey macrovalue

logmacro delete macrokey

logmacro print[,sortopt] [ macrokey ]

logmacro names[,sortopt]

where macrokey is of the form [ SYS=scrnname ] NAME=name macrovalue is of the form VALUE=macrobody sortopt is one of asc, desc, iasc

(For example, desc specifies a plaintext description string desc to be associated with the object.

logstats Subcommand

ssadm logstats prints information about the SunScreen log.

Usage:

ssadm logstats

patch Subcommand

ssadm patch installs a patch, as needed.

Usage:

For stealth-mode Screens from Remote Administration Stations, use:

ssadm [-r screen_name] patch Install [NOREBOOT] < patch.tar.Z

ssadm [-r screen_name] patch Backout [NOREBOOT] patchID

On routing-mode Screens, the standard Solaris patchadd and patchrm commands can be used.

If a SunScreen software patch is needed, detailed instructions are provided with the patch.

policy Subcommand

ssadm policy creates, deletes, renames, or lists the defined policies.

Usage:

ssadm policy -a policies...

ssadm policy -c oldname newname

ssadm policy -d [-v] policies...

ssadm policy -l [-v] [policies...]

ssadm policy -r oldname newname

TABLE B-6 describes the options for this command.

Table B-6 Options for policy Subcommand

Options 

Description 

-a

Creates policies with the specified names. The newly created policies contain no rules and references the currently defined common objects. 

-c

Creates a policy named newname as a copy of the existing policy named oldname.

-d

Deletes the named policies. The specified policies can be either generic policy names, such as Initial, or specific versions, such as "Initial.3". When a generic policy name is specified and the -v option is specified, ssadm policy -d deletes all of the versions of the policy. When a specific version is specified, only that version is deleted.

-l

Lists the named policies (or all policies available if no policies are given). The -v option also lists all of the saved versions of the policies.

-r

Renames the existing policy oldname to newname.

product Subcommand

ssadm product prints out a single line of text describing the SunScreen product in use.

Usage:

ssadm product

restore Subcommand

ssadm restore reads a backup file from standard input. The backup file must have been created using the backup command.

Usage:

ssadm restore < file

spf2efs Subcommand

ssadm spf2efs converts a set of configuration data saved from a SunScreen SPF-2000 Screen into SunScreen format.

Usage:

ssadm spf2efs < file

sys_info Subcommand

ssadm sys_info prints a description of the running SunScreen software.

Usage:

ssadm sys_info

For example:


# ssadm sys_info
Product: 											SunScreen
System Boot Time: 											03/15/1999 03:51 PST
SunScreen Boot Time: 											Mon Mar 13 03:51:56 PST 200
Version: 											Release 3.1, March 10 
											2000(v0310991418)

traffic_stats Subcommand

ssadm traffic_stats reports summary information about the traffic flowing through the Screen, classified by interface.

Usage:

ssadm traffic_stats [interfaces...]