Configuration Editor

The configuration editor is the primary command-line tool for creating and manipulating the objects that control the operation of a Screen.

Configuration Editor Data Model

TABLE B-8 lists the data types that compose the Data Model as maintained by the configuration editor (ssadm edit) and the ssadm policy command.

Object types marked as having common storage in the table are normally stored in the common objects registry that is not part of any particular policy. These objects are used by all policies, so changes to the common objects can affect the behavior of multiple policies. To edit the common objects, it is necessary to specify a policy name when starting the configuration editor even if you are not modifying any policy objects.

Object types marked as having policy storage in the table are stored as part of a policy. Policy objects often refer to common objects and, therefore, can have different meaning depending on the value of common objects. For example, a policy can contain a rule object that allows address A to communicate with address B. The address objects A and B are defined in the common objects.

Object types marked as having external storage in the table are almost equivalent to common objects, but they are stored in a separate database that is not affected by the quit, reload, or save commands. Changes to these objects are always immediate, and persist even if the save command is not used.

Object types marked as having policy list storage in the table represents the names of the policies themselves. Minimal capabilities are provided by the configuration editor to manage the policy. A policy currently being edited can be saved or cloned (or portions of it) into a new policy. Other policy requests, such as add, delete, and rename are provided by the ssadm policy command.

Configuration Editor Commands

The ssadm edit commands are used when running the configuration editor, which is responsible for maintaining the SunScreen configuration database.

TABLE B-9 lists the SunScreen configuration editor ssadm edit subcommands and their descriptions. Many subcommands duplicate administration GUI functions, while others provide a context for other subcommands.

In the following command descriptions, when the name of an object of a particular TYPE is required, it is indicated by name_TYPE. If an index is needed, it is indicated by #. A keyword that was required in previous SunScreen releases but is now optional, is indicated by KEYWORD.

add Subcommand

Creates or redefines an entry.

Usage:

add TYPE parameters...

If a named-type is specified and an entry with that name already exists, it is replaced with the new entry. If it does not exist, one is created with the new name. All of the following have a similar request of add_nocheck, which does not perform consistency checking.

add address Subcommand

add address "name_ADDRESS" <HOST> #.#.#.#

add address "name_ADDRESS" <RANGE> #.#.#.# #.#.#.#

add address "name_ADDRESS" <GROUP> { "name_ADDRESS" ... } { "name_ADDRESS" ... }

The following fields are optional and can be specified in any order after the address keyword:

SCREEN "name_SCREEN"

COMMENT "comment string"

The addresses * and localhost are reserved and cannot be edited.

add screen Subcommand

add screen "name_SCREEN"

The following fields are optional and can be specified in any order after the screen keyword:

MASTER "name_SCREEN"

HA_PRIMARY

HA_SECONDARY

TIMEOUT #

SNMP #.#.#.# ... (list can be empty; not output if empty list)

SNMP_TIMER # (if SNMP is set)

CDP {"on" if present, "off" otherwise}

RIP {"on" if present, "off" otherwise}

DNS {"on" if present, "off" otherwise}

NIS {"on" if present, "off" otherwise}

LOGSIZE # {default is 100 MBytes if not present}

STEALTH_NET #.#.#.# #.#.#.# {Network and Netmask for stealth type Interfaces}

HA_IP #.#.#.# (required if HA_PRIMARY is set)

HA_ETHER xx:xx:xx:xx:xx:xx (required if HA_PRIMARY is set)

COMMENT "comment string"

If the Screen is to be a part of an HA cluster, and administered remotely, then the following fields must be specified as well. They can be specified in any order after the screen keyword:

ADMIN_IP #.#.#.# or name_ADDRESS

ADMIN_CERTIFICATE "name_CERTIFICATE"

KEY "name_KEY_ALGORITHM"

DATA "name_DATA_ALGORITHM"

MAC "name_MAC_ALGORITHM"

COMPRESSION "name_COMPRESSION_ALGORITHM"

TUNNEL "name_ADDRESS"

The screen * is reserved and cannot be edited.

add service Subcommand

add service "name_SERVICE" <SINGLE> filter ...

add service "name_SERVICE" GROUP "name_SERVICE" ...

For SINGLE services, a list of Filters follows the SINGLE keyword. The list must not be empty. Each Discriminator list also must not be empty. A Filter is of the form:

FORWARD "name_STATEENGINE" discriminator ...

REVERSE "name_STATEENGINE" discriminator ...

An individual discriminator is as follows:

PORT #

PORT #-# (Note, no space is allowed before or after the - character)

BROADCAST #

BROADCAST #-#

An optional parameter for discriminators, which appears immediately after the number or range it modifies, is:

PARAMETERS space-separated list of #

For GROUP services, a space-separated list of "name_SERVICE" entries follows the GROUP keyword.

The following fields are optional and can be specified in any order after the service keyword:

SCREEN "name_SCREEN"

COMMENT "comment string"

add interface Subcommand

add interface "name_INTERFACE" type "name_ADDRESS"

type must be one of ADMIN, DISABLED, ROUTING, HA, or STEALTH.

The following fields are optional for stealth interface types and can be specified in any order after the interface keyword. Up to 5 ROUTERs per stealth interface can be specified. More can be specified, but only 5 (no guarantee in which order) are used by the system.

ROUTER #.#.#.#

The following fields are optional for all interface types and can be specified in any order after the "interface" keyword:

SCREEN "name_SCREEN"

COMMENT "comment string"

The following fields are optional for all interface types except DISABLED and can be specified in any order after the interface keyword.

LOG NONE {default if no LOG is specified}

LOG SUMMARY LOG DETAILED

ICMP NONE

ICMP NET_UNREACHABLE

ICMP HOST_UNREACHABLE

ICMP PORT_UNREACHABLE

ICMP NET_FORBIDDEN

ICMP HOST_FORBIDDEN

SNMP {"on" if present, "off" otherwise}

add certificate Subcommand

add certificate "name_CERTIFICATE" SINGLE NSID # MKID "#"

add certificate "name_CERTIFICATE" GROUP "name_CERTIFICATE" ...

For GROUP certificates, a space-separated list of name_CERTIFICATE entries follows the GROUP keyword.

The following fields are optional for SINGLE entries and may be specified in any order after the certificate keyword:

G #

P #

KEY_LENGTH #

LOCAL "name_SCREEN"

The following fields are optional and can be specified in any order after the "certificate" keyword:

SCREEN "name_SCREEN"

COMMENT "comment string"

add time Subcommand

add time "name_TIME"

The following fields are optional and can be specified in any order after the time keyword:

EVERYDAY

SUNDAY

MONDAY

TUESDAY

WEDNESDAY

THURSDAY

FRIDAY

SATURDAY

SCREEN "name_SCREEN"

COMMENT "comment string"

The time object * cannot be modified.

Following any of the *DAY keywords can be a time of day specification in the form {timespec ...} . timespec is a time range in the form:

Start Hour:Start Minute Stop Hour:Stop Minute

Examples are: { 1:00 2:30 } and { 1:00 2:30 4:00 6:00 }. Twenty-four-hour time format is used, so the valid times are 0:00 (starting at midnight) through 24:00 (ending at midnight).

add rule Subcommand

add rule "name_SERVICE" name_ADDRESS

Appends the rule to the end of the list of rules in the policy. insert rule should be used to position a new rule into an existing policy.

The following fields are optional and can be specified in any order after the rule keyword:

ALLOW {default if no ACTION specified}

DENY

LOG NONE {also LOG_NONE, default if no LOG is specified}

LOG SUMMARY {also LOG_SUMMARY}

LOG DETAILED {also LOG_DETAILED}

LOG SESSION {also LOG_SESSION, only valid for ALLOW rules, will be error for DENY}

SNMP {"on" if present, "off" otherwise}

USER "name_USER" {only used if PROXY_FTP or PROXY_Telnet set below }

TIME "name_TIME"

SCREEN "name_SCREEN"

COMMENT "comment string"

The following combo-field is optional and only valid in a rule that has ALLOW specified. It can be specified anywhere after the rule keyword:

SKIP_VERSION_1 "name_CERTIFICATE" "name_CERTIFICATE" "name_KEY_ALGORITHM" "name_DATA_ALGORITHM"

SKIP_VERSION_2 "name_CERTIFICATE" "name_CERTIFICATE" "name_KEY_ALGORITHM" "name_DATA_ALGORITHM" "name_MAC_ALGORITHM" "name_COMPRESSION_ALGORITHM"

The following fields are optional and only valid within a SKIP_VERSION_1 or SKIP_VERSION_2 combo-field. They can be specified in any order after the SKIP_VERSION_# keyword:

SOURCE_TUNNEL "name_ADDRESS"

DESTINATION_TUNNEL "name_ADDRESS"

The following field is optional and only valid in a rule that has DENY specified. It can be specified anywhere after the rule keyword:

ICMP NONE {also ICMP_NONE, default if nothing is specified}

ICMP NET_UNREACHABLE {also ICMP_NET_UNREACHABLE}

ICMP HOST_UNREACHABLE {also ICMP_HOST_UNREACHABLE}

ICMP PORT_UNREACHABLE {also ICMP_PORT_UNREACHABLE}

ICMP NET_FORBIDDEN {also ICMP_NET_FORBIDDEN}

ICMP HOST_FORBIDDEN {also ICMP_HOST_FORBIDDEN}

The following field is optional and only valid in a rule that has ALLOW specified and NO SKIP information. It can be specified anywhere after the rule keyword:

VPN "name_VPN"

The following fields are optional and only valid in a rule that has not specified any SKIP information and no VPN. They can be specified anywhere after the rule keyword. Only one of them can be specified in a given rule.

PROXY_FTP

PROXY_HTTP

PROXY_SMTP

PROXY_Telnet

The following fields are optional and only valid in a rule that has specified PROXY_FTP. They can be specified anywhere after the PROXY_FTP keyword:

FTP_GET

NO_FTP_GET {default if FTP_GET not specified}

FTP_PUT

NO_FTP_PUT (default if FTP_PUT not specified}

FTP_CHDIR

NO_FTP_CHDIR {default if FTP_CHDIR not specified}

FTP_MKDIR

NO_FTP_MKDIR {default if FTP_MKDIR not specified}

FTP_RENAME

NO_FTP_RENAME {default if FTP_RENAME not specified}

FTP_REMOVE_DIR

NO_FTP_REMOVE_DIR {default if FTP_REMOVE_DIR not specified}

FTP_DELETE

NO_FTP_DELETE {default if FTP_DELETE not specified}

The following fields are optional and only valid in a rule that has specified PROXY_HTTP. They can be specified anywhere after the PROXY_HTTP keyword:

COOKIES

NO_COOKIES {default if COOKIES not specified}

ACTIVE_X

NO_ACTIVE_X {default if ACTIVE_X not specified}

SSL

NO_SSL {default if SSL not specified}

JAVA_SIGNATURE

JAVA_HASH

JAVA_SIGNATURE_HASH

JAVA

NO_JAVA {default if no other JAVA setting is specified}

The following fields are optional and only valid in a rule that has specified PROXY_SMTP. They can be specified anywhere after the PROXY_SMTP keyword: RELAY

NO_RELAY {default if RELAY not specified}

add nat Subcommand

add nat STATIC "name_ADDRESS" "name_ADDRESS" "name_ADDRESS" "name_ADDRESS"

add nat DYNAMIC "name_ADDRESS" "name_ADDRESS" "name_ADDRESS" "name_ADDRESS"

The following fields are optional and can be specified in any order after the nat keyword:

SCREEN "name_SCREEN"

COMMENT "comment string"

add accesslocal Subcommand

add accesslocal USER "name_USER"

The following fields are optional and can be specified in any order after the accesslocal keyword:

SCREEN "name_SCREEN"

COMMENT "comment string"

add accessremote Subcommand

add accessremote USER "name_USER" "name_ADDRESS" SKIP_VERSION_1 "name_CERTIFICATE" "name_KEY_ALGORITHM" "name_DATA_ALGORITHM"

add accessremote USER "name_USER" "name_ADDRESS" SKIP_VERSION_2 "name_CERTIFICATE" "name_KEY_ALGORITHM" "name_DATA_ALGORITHM" "name_MAC_ALGORITHM" "name_COMPRESSION_ALGORITHM"

The following field is optional for accessremote entries. It can be specified in any order after the accessremote keyword:

TUNNEL "name_ADDRESS" { if the remote machine is using tunneling }

The following fields are optional and can be specified in any order after the accesslocal/accessremote keyword:

PERMISSION ALL

PERMISSION WRITE

PERMISSION READ

PERMISSION STATUS

PERMISSION NONE { default if no PERMISSION is specified }

SCREEN "name_SCREEN"

COMMENT "comment string"

add vpngateway Subcommand

add vpngateway "name_VPN" "name_ADDRESS" SKIP "name_CERTIFICATE"

The following fields are required and can be specified in any order after the vpngateway keyword:

KEY "name_KEY_ALGORITHM"

DATA "name_DATA_ALGORITHM"

MAC "name_MAC_ALGORITHM"

COMPRESSION "name_COMPRESSION_ALGORITHM"

The following fields are optional and can be specified in any order after the "vpngateway" keyword:

TUNNEL "name_ADDRESS"

COMMENT "comment string"

add_member Subcommand

Adds a member to a group or list.

Usage:

add_member address "name_ADDRESS" "name_ADDRESS"* { add to include list }

add_member address "name_ADDRESS" EXCLUDE "name_ADDRESS"* { add to exclude list }

add_member service "name_SERVICE" "name_SERVICE"*

add_member certificate "name_CERTIFICATE" "name_CERTIFICATE"*

 * denotes that multiple space-separated names can be specified in a single request.

The following field may be necessary to uniquely identify an entry. If so, it can be specified after the TYPE keyword:

SCREEN "name_SCREEN"

authuser Subcommand

Manipulates the list of authorized users.

Usage:

authuser add name parameters...

authuser delete name

authuser print

delete Subcommand

Deletes the specified entry of the given TYPE.

Usage:

del[ete] address "name_ADDRESS"

*del[ete] screen "name_SUNSCREEN"

del[ete] service "name_SERVICE"

del[ete] interface "name_INTERFACE"

del[ete] certificate "name_CERTIFICATE"

del[ete] time "name_TIME"

*del[ete] rule #

*del[ete] nat #

*del[ete] accesslocal #

*del[ete] accessremote #

*del[ete] vpngateway #

The following field may be necessary to uniquely identify an entry. If so it can be specified after the TYPE keyword, except for the entries preceded by an * above:

SCREEN "name_SCREEN"

delete_member Subcommand

Deletes a member from a group or list.

Usage:

del[ete]_member address "name_ADDRESS" "name_ADDRESS"* { from include list }

del[ete]_member address "name_ADDRESS" EXCLUDE "name_ADDRESS"* { from exclude list }

del[ete]_member service "name_SERVICE" "name_SERVICE"*

del[ete]_member certificate "name_CERTIFICATE" "name_CERTIFICATE"*

 *  denotes that multiple space-separated names can be specified in a single request.

The following field may be necessary to uniquely identify an entry. If so it can be specified after the TYPE keyword:

SCREEN "name_SCREEN"

insert Subcommand

Inserts a new object of one of the ordered (indexed) types in a specified position in the corresponding list.

Usage:

insert rule # parameters...

insert nat # parameters...

insert accesslocal # parameters...

insert accessremote # parameters...

insert vpngateway # parameters...

Index indicates the position the new entry holds in the list after it is inserted. The same syntax used for add is used for insert, with the index coming immediately after the TYPE keyword.

jar_hash Subcommand

Manipulates the list of JAR hashes used by the HTTP proxy.

Usage:

jar_hash add name hash

jar_hash delete name

jar_hash rename oldname newname

jar_hash list

jar_hash list_names

TABLE B-10 describes the functions for this command.

jar_sig Subcommand

Manipulates the list of JAR signatures used by the HTTP proxy.

Usage:

jar_sig add name sig-hash

jar_sig delete name

jar_sig rename oldname newname

jar_sig list

jar_sig list_names

TABLE B-11 describes the functions for this command.

list Subcommand

Displays all data for all entries or a specific entry of a given TYPE. The format of the output is the same as the syntax of the corresponding Add TYPE request.

Usage:

*list address

list address "name_ADDRESS"

*list screen

*list screen "name_SCREEN"

*list service

list service "name_SERVICE"

*list stateengine

*list stateengine "name_STATEENGINE"

*list interface

list interface "name_INTERFACE"

*list certificate

list certificate "name_CERTIFICATE"

*list time

list time "name_TIME"

*list rule

*list rule #

*list nat

*list nat #

*list accesslocal

*list accesslocal #

*list accessremote

*list accessremote #

*list vpngateway

*list vpngateway #

The following field is optional and can be specified after the TYPE keyword in any of the above requests except those that are preceded by an * .

SCREEN "name_SCREEN"

If no SCREEN option is present, only entries not associated with a specific SCREEN are listed. If the SCREEN option value is * , then all entries that otherwise match are displayed. Requests that do not specify a name always display all entries of the given type.

list_name Subcommand

Displays the set of unique basenames and subtype of all of a given TYPE. These are the values that can be used when another object refers to an object of the specified TYPE.

Usage:

list_name TYPE

TYPE can be any of address, screen, service, state engine, interface, certificate, time, or vpn.

load Subcommand

Loads a policy into the configuration editor.

Usage:

load "name_POLICY"

Any edits to the current policy must be saved or discarded before this operation will succeed.

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

lock_status Subcommand

Returns the status of the Lock relative to this editor. If this editor holds a lock, the type of lock is returned. If it does not hold a lock, another process acquired a WRITE lock, in which case, if that WRITE lock is still in effect, information about that WRITER is presented. If that WRITE lock is no longer in effect, then Lock available is returned.

Usage:

lock_status

search Subcommand

Searches the Registry for objects that match specified criteria.

Usage:

search TYPE [SCREEN "name_SCREEN"] [ SUBTYPE subtype ] <EXACT> Substring...

TYPE can be any of address, screen, service, stateengine, interface, certificate, or time. SUBTYPE values depend upon the TYPE being searched according to TABLE B-12.

The EXACT keyword requires a substring be specified and will on match entries whose name is an exact match.

move Subcommand

Moves an indexed entry from its current location in the ordered list to the new location.

Usage:

move rule # #

move nat # #

move accesslocal # #

move accessremote # #

move vpngateway # #

replace Subcommand

Replaces an object at a specified index.

Usage:

replace rule # parameters...

replace nat # parameters...

replace accesslocal # parameters...

replace accessremote # parameters...

replace vpngateway # parameters...

replace is similar to insert, except it replaces the entry at the specified index. It is shorthand for an insert n / del n+1 pair of requests. The same syntax used for add is used for replace, with the index coming immediately after the TYPE keyword.

refer Subcommand

Determines if a named objects of a given TYPE is referred to in the common data or the current policy.

Usage:

refer address "name_ADDRESS"

refer screen "name_SCREEN"

refer service "name_SERVICE"

refer stateengine "name_STATEENGINE"

refer certificate "name_CERTIFICATE"

refer time "name_TIME"

refer vpn "name_VPN"

referlist Subcommand

Displays a list of all entries in the common objects and/or the current policy that refer to a specified named-object of a given TYPE.

Usage:

referlist address "name_ADDRESS"

referlist screen "name_SCREEN"

referlist screen "name_SCREEN"

referlist service "name_SERVICE"

referlist stateengine "name_STATEENGINE"

referlist certificate "name_CERTIFICATE"

referlist time "name_TIME"

referlist vpn "name_VPN"

rename Subcommand

Renames a specified named-object of a given TYPE.

Usage:

rename address "name_ADDRESS" "name_ADDRESS"

*rename screen "name_SCREEN" "name_SCREEN"

rename service "name_SERVICE" "name_SERVICE"

rename interface "name_INTERFACE" "name_INTERFACE"

rename certificate "name_CERTIFICATE" "name_CERTIFICATE"

rename time "name_TIME" "name_TIME"

The following field may be necessary to uniquely identify an entry. If so it can be specified after the TYPE keyword except for the entries preceded by an * above:

SCREEN "name_SCREEN"

If an entry already exists with the new name, it is replaced by this operation.

renamereference Subcommand

Renames all references to a specified named-object of a given TYPE.

Usage:

renamereference address "name_ADDRESS" "name_ADDRESS"

renamereference screen "name_SCREEN" "name_SCREEN"

renamereference service "name_SERVICE" "name_SERVICE"

renamereference certificate "name_CERTIFICATE" "name_CERTIFICATE"

renamereference time "name_TIME" "name_TIME"

renamereference vpn "name_VPN" "name_VPN"

save Subcommand

Saves any current edits. It also creates a new version of the policy.

Usage:

save

save "name_POLICY"

If a name is specified, then the current policy is written to the new name, but the old policy remains the policy in the editor.

saveas Subcommand

Saves the data currently in the editor under a new name.

Usage:

saveas

saveas policy "name_POLICY"

saveas policy "name_POLICY" registry Registry

saveas policy "name_POLICY" registry "name_POLICY"

saveas policy registry Registry

These are the only supported legal requests. The first saves the current policy data under the new name with a reference to the current common objects. The second saves the policy data under the new name and overwrites the current common objects with whatever is currently in the editor. This may affect other policies and should be done with caution. The third saves the contents of the editor, policy objects and common objects, into a single self-contained policy file of the specified name. The last saves the common objects currently in the editor as the current common objects and may impact other policies and should be done with caution.

reload Subcommand

Discards any and all edits (if any were made) and reloads the data into the editor from the database. If another process has performed edits and saved them since the current editor process loaded its data, and the current editor process wants to perform edits, it must perform a reload first, to reacquire its read lock and ensure that no saved edits are lost.

Usage:

reload

verify Subcommand

Takes no arguments and verifies the currently loaded policy.

Usage:

verify

mail_relay Subcommand

Manipulates the list of mail relays used by the SMTP proxy.

Usage:

mail_relay parameters

mail_spam Subcommand

Manipulates the list of spam domains used by the SMTP proxy.

Usage:

mail_spam add domain-string

mail_spam del domain-string

mail_spam list

proxyuser Subcommand

Manipulates the list of proxy users.

Usage:

proxyuser add name parameters...

proxyuser delete name

proxyuser print

vars Subcommand

Manipulates variables used for RADIUS configuration.

Usage:

vars add variables

quit Subcommand

Causes the editor to terminate if there are no unsaved changes.

Usage:

quit

When the editor is used interactively, typing quit twice consecutively causes the editor to terminate even if there are unsaved changes.

QUIT Subcommand

QUIT (typed in upper case) causes the editor to terminate even if there are unsaved changes.

Usage:

QUIT