SunScreen EFS Release 3.0 Reference Manual

Chapter 4 SunScreen EFS 3.0 Logs

SunScreen EFS 3.0 provides flexible logging of packets. You can configure SunScreen EFS 3.0 to log a packet when it matches a rule or when it does not match any particular rule. Most frequently, packets matching DENY rules or packets that are dropped because they do not match any rule are logged. The action definition of a rule controls whether a packet is logged and what information about the packet is recorded.

Examining logged packets is useful when you are identifying the causes of problems during configuration or administration of your SunScreen EFS 3.0. You should also examine logs periodically for evidence of attempts to break into your network.

Logging Limitations

During a situation or time when there is excessive traffic through the Screen, not all packets are logged.

This logging limitation is an isolated instance and depends on how fast your system runs.
Decrypted packets are logged, but SKIP certificate IDs are not logged.

SunScreen EFS 3.0 cannot guarantee the identity of who is coming through the firewall from an audit point of view.
Only the active system logs packets.

When the active HA cluster Screen fails, its logs are lost, and the new active HA cluster Screen begins logging the packets.

Log File Locations

SunScreen EFS 3.0 stores its log files in the following locations:

The SunScreen EFS 3.0 packet, session, and extended event log is stored on the Screen in the /var/opt/SUNWicg/SunScreen/logs directory.

SKIP logs are kept in the /var/log/ directory.

High availability (HA) event logs are logged according to the configuration settings for syslog.

Configuring Traffic Log Size

In SunScreen EFS 3.0, the size of the area used to log packet traffic, session and other events is configurable. The og file contains a number of files in a particular directory. Each Screen has a log file of its own, and the size of the log file on each Screen can be configured specifically.

Log file sizes are established in much the same way as other configuration items, and these sizes are propagated to various Screens being managed during the normal activation process. However, the actual resizing of the log file on a particular Screen only occurs on the next restart of that Screen after the activation that changes the size. This is true for primary and secondary Screens in a Centralized Management group and in an HA cluster.

It is advisable that changes to the log file size(s) be made during initial Screen installation because resizing of the log file on a particular Screen only occurs on the next restart of that Screen, after the activation that changes the size.

Note -

Setting the size of the log file does not cause immediate allocation of the filesystem space to store the log. Hence, other competing users of the filesystem on which the log file resides should not be allowed to consume this space. Even when the log has filled and begins to reuse filesystem space, the maximum amount of filesystem space is still not in use at all times.

Configuring the Global Default Log Size

The global default log size is controlled by the variable LogSize. It contains the following items:

prg=logname=LogSizevalue=size	(in Mbyte units)

description="descriptive text"	(optional)

enabled | disabled	(default is enabled)

The global default log size can only be configured using the command line interface (see Appendix B).

Group-Screen installations are configured on the primary Screen.

The following is an example of what you type to display the global default log file size, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> vars print prg=log name=LogSize PRG="log" NAME="LogSize" ENABLED VALUE="100" DESCRIPTION="global
log capacity (MB)" ...

The following is an example of what you type to set the global default log file size, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> vars add prg=log name=LogSize value=new size description=new description
edit> quit

Tip -

It is not necessary to type save before quit above if only authuser, proxyuser, logmacro, or vars entities are altered.

The following is an example of what you type to set the global default log file size to 250 Mbytes, while logged in to the primary Screen:

edit> vars add prg=log name=LogSize value=250 description="log size (MB)"

Note -

Although, the output produced by print surrounds the value of each item in double quotes, these are only necessary on input to protect embedded spaces within the values of items. Also, although print outputs all tag names in capital letters (for example, PRG=), these tags are recognized in a case-insensitive manner on input (for example, prg=, Prg=, PRG= are equivalent).

The following is an example of what you see if you attempt to save without changing entities other than these types, you are reminded by a message:

edit> savelock not held
failed (status 244)

This is a non-fatal message and you can simply quit the configuration editor.

Once a log file size has been changed, the system configuration must be activated to propagate the change. Then the effected Screen(s) must be restarted for the log file size change to take effect. (In the case of a change to the global default log file size, the effected Screens are all Screens except those for which a log file size has been specifically configured.)

Configuring the Log Size for a Specific Screen

Configuring the global log size for a centralized management group of Screens, or Screens in an HA cluster, is performed on the primary Screen through the administration GUI.

Global log size is also configured through the command line (see Appendix B). It is controlled by the variable LogSize.

The following is an example of what you type to display the log file size for a specific Screen, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> list Screen scrn1 ADMIN_CERTIFICATE "scrn1.admin" CDP ROUTING DNS scrn2 ADMIN_CERTIFICATE "scrn2.admin" CDP ROUTING DNS LOGSIZE 444

scrn1 does not have the log file size configured and so uses the global default value. scrn2 has a size of 444 (Mbytes) that is used instead of the global default value on that Screen.

The following is an example of what you type to set the log file size for a specific Screen, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> add Screen scrn1 ADMIN_CERTIFICATE scrn1.admin CDP ROUTING DNS LOGSIZE 20
edit> save
edit> quit

Note -

When altering the value of LogSize, be sure to reenter all the other attributes as they were displayed by the list verb.

The following is an example of how you would alter the log file size for a specific Screen through the administration GUI:

From the Policies page, select and edit the policy to be altered.

Select the desired Type: "Screen common object."

Edit the Screen's common object.

Alter the Log Size entry through the Miscellaneous tab.

Save the change in Save Changes.

Activate the policy.

Restart the Screen for the log file size change to take effect.

Configuring Events to be Logged

Logs contain three basic types of events:

network traffic (packet)
network session summaries
extended events

For a given program component, the level of logging can be specified. This is done by means of a variable setting for that component; the name of the variable is LogSeverity. A variable that is specific to a particular Screen overrides the general setting for that component. Beyond the variable setting for a specific component, a general (non-component-specific) variable controls otherwise unlimited logging; again, a variable that is specific to a given Screen overrides this general default. This search order can be summarized as:

	Key Sought
	---------------------------------------------------
sys=Screenname prg=programname 

name=LogSeverityprg=programname name=LogSeveritysys=Screenname name=LogSeverityname=LogSeverity

As initially configured, SunScreen EFS 3.0 contains variables defined for each program components logging variable, along with the non-component non-Screen (global global) default; all are initially set to the value "info".

Configuring events to be logged can only be configured using the command line interface.

Configuring Log Event Limiters

The log limiters are controlled by LogSeverity variables as previously introduced. Each such variable contains the following items:

sys=Screenname		(optional)

prg=programname		(optional)

name=LogSeverityvalue=severityname		(emerg,alert,...,debug)

description="descriptive text"		(optional)

enabled | disabled		(default is enabled)

The LogSeverity variables can only be configured using the command line interface (see Appendix B). For group-Screen installations, they are configured on the primary Screen.

The following is an example of what you type to display the global global log limiter, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> vars print name=LogSeverity
NAME="LogSeverity" ENABLED VALUE="INFO" DESCRIPTION="global log
severity limit" ...

The following is an example of what you type to display the global log limiter for authentication events, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> vars print prg=auth name=LogSeverity
PRG="auth" NAME="LogSeverity" ENABLED VALUE="INFO" DESCRIPTION="global log severity limit,
authentication" ...

The following is an example of what you type to cause more (debugging) information to be logged on a particular Screen for authentication events, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> vars add sys=Screenname prg=auth name=LogSeverity value=debug description="debug authentication operations"
edit> quit

Note -

The following is an example of the message you see if you attempt to save without changing entities other than these types:

edit> savelock not held
failed (status 244)

This is a non-fatal message and you can simply quit the configuration editor.

Once log limiters have been altered, the configuration must be activated to propagate the changes.

Log Retrieval and Clearing

A Screens log is retrieved and can be cleared using the log sub-command of ssadm. Filtering can be applied by the Screen during retrieval, reducing the content of the log retrieved (see the section, "Log Inspection and Browsing").

You can retrieve and post-process logs on an automated basis (details regarding automated log management can be found in the man page for sslogmgmt(1M)). The maintenance command sslogmgmt(1M) automates management of SunScreen logs for a group of centrally managed Screens. It can be run manually as it is designed to run as a cron(1M) job. It is available through SUNWicgSA.

log has three sub-commands:

`get`	Retrieves the current content of the log, but leaves it intact.
`get_and_clear`	Combines these two functions, clearing the log through the point to which it was retrieved.
`clear`	Makes the current content of the log inaccessible for further retrieval operations.

Retrieval of the log produces the (binary) log records on the standard output of ssadm. This is either redirected to a file or perhaps piped into other processes, such as ssadm logdump for viewing, further filtering, and so forth. Manipulation of the output stream should be performed by the shell you are using on your administration platform.

Note -

The get_and_clear operation clears the log when the Screen producing the log finishes writing to the connection used to retrieve it. If the administration platform crashes, the disk to which the log is being written fills, or other exceptional conditions occur near the end of the retrieval, the clear phase can complete and some log records can be lost.

The following is an example of what you type to get the log from a given (primary or secondary) Screen to store in a local file:

admin% ssadm -r Screen log get [filterarg ...] > locallogfile

The following is an example of what you type to get and clear the log automatically:

admin% ssadm -r Screen log get_and_clear [filterarg ...] > locallogfile

The following is an example of what you type to simply clear the log:

admin% ssadm -r Screen log clear

The get_and_clear and clear verbs take an optional argument: a designation of who cleared the log. This is a text string that is displayed when log statistics are retrieved.

The following is an example of what you type to get and clear the log, setting this designator:

admin% ssadm -r Screen log -U "ben" get_and_clear [filterarg ...] > ...

The following is an example of what you type to simply clear the log, setting this designator:

admin% ssadm -r Screen log -U "Ben:
reset after move" clear

Log Statistics

The current statistics of a Screens log file can be inspected in the administration GUI-based log browser.

These same statistics are also visible using the logstats sub-command of ssadm.

Note -

You must enter the name of the Admin Interface of the Screen as listed in the Naming Service or in the hosts file.

`ssadm logstats` Sub-Command

The following is an example of what you type to display the statistics for the log on a given (primary or secondary) Screen, while logged into that Screen:

admin% ssadm -r Screen logstatsLog size (bytes): 170600
Log maximum size (bytes): 60000000
Log loss count (records): 0
Cleared at: 04/01/1999 17:43 PST

The Log size item details the number of bytes currently contained in the log. Log maximum size gives the (rough) upper bound on the size of the log file (it is the configured log file size multiplied by one million). Both of these sizes indicate only the space to store the logged records, not the additional (though minimal) space needed to manage those records.

The Log loss count gives the number of records that the logging server has discarded due to the log wrapping around before being retrieved or cleared.

The Cleared at: gives the date and time the log was last cleared. If a text designator (through the -U option to the log verb) was given during the operation that cleared the log, then this line has the form:

Cleared by: ben at 04/01/1999 17:43
PST

Log Inspection and Browsing

Log mechanisms, processed through user-defined or ad-hoc filters, provide the ability to inspect previously retrieved stored logs. The results are either stored as logs or converted to displayable text. Using the administration GUI, a Screens active log file can be browsed in either a historical or live mode.

Note -

You must enter the name of the Admin Interface of the Screen as listed in the Naming Service or in the hosts file.

Log Filters and the `logdump` Command

Filtering Screen's logs employs a common filtering mechanism and language, regardless of the context in which it is used, that is embodied in the logdump command. logdump is based on, and is a superset of, the snoop program, which is provided with the standard Solaris operating system platform.

logdump can be used on an Administration Station to filter and inspect logs during active retrieval or on logs previously retrieved and stored. In conjunction with the logmacro facility, pre-defined filters can be employed to simplify and regularize routine log processing tasks.

The general usage for logdump is as a sub-command of ssadm. ssadm provides character-set translation between strings embedded in log events and the local character set of the Solaris system on which it runs.

Reminder: although logdump is used directly as an ssadm sub-command, all other places in SunScreen where log filtering is allowed employ the same filter specification language. Hence, examples in this manual section should be viewed as prototypical of these other usage contexts.

Nominally, logdump input is either a log record stream directly from a possibly remote Screen, or captured log records from a file. This source of input is specified by the -i option.

The following is an example of what you type to process (piped-in) records from the standard input:

% ssadm -r Screen log get | ssadm logdump -i- [output args ...] [filter args ...]

The following is an example of what you type to process local file log record input:

% ssadm logdump -i locallogfile [output args ...] [filter args ...]

logdump fundamentally outputs either a stream of log records, or readable text in various formats (after applying specified filters).

The presence of the -o option causes (binary) log records to be produced, for example:

% ... ssadm logdump -iinput arg -o- [filter args ...] | ...
or:
% ... ssadm logdump -iinput arg -olocallogfile [filter args ...]

To output readable text, omit the -o option.

The formatting options for readable text are common to snoop; these are -v, -V, -t[r|a|d], and -xoffset[,length].

`logdump` Extensions

logdump is an extension of the standard snoop packet monitoring tool provided with the Solaris operating system. In general, any expertise in the use of snoop is directly applicable to use of logdump.

The facilities of logdump that are common to snoop are not detailed here; refer to the ssadm-logdump(1m) man page.

logdump has been extended to provide for the special additional needs of the SunScreen system. These extensions are summarized as:

Extensions to the format of network packets logged: inclusion of the interface on which logged packets arrive inclusion of the reason (why) packets are logged
Provisions for SUMMARY logging (wherein only a size-limited packet preamble is logged)
Logging of network packets on routing mode (ROUTING) interfaces removes the MAC-layer header
Addition of session- and extended-log events (previously described)
Enforcement and synthesis of unique timestamps
True filter (pipeable) processing (standard snoop can process a captured packet stream, or produce a captured packet stream, but not both -- logdump allows both)
Addition of filtering operators for selection of various log event types (loglvl), event severity (logsev), logging program component (logapp), packet log interface (logiface), and packet log reason (logwhy)
Addition of range operands for IP addresses and port numbers to mirror the semantics of SunScreen address objects
Display of SKIP packet encapsulations
Display of all extensions listed above

logdump is also fundamentally different from snoop in the respect that it is not involved in decisions as to what is logged by SunScreen (rules and variables previously described provide this control). Rather logdump serves as a means to post-process log file content only. (snoop is often used to filter network input during the process of capture or direct display.)

SunScreen logs and snoop capture files are not interoperable.

Logged Network Packet Enhancements

On SunScreen, the log contains network traffic that arrives on multiple link-layer interfaces in a con temporally-interspersed manner. For this reason, it is important to record the interface upon which the traffic was received. The interface is memorialized by the name of its Solaris device (for example, le0, elx0).

Note -

For snoop, the interface being monitored is specified as a command-line option. This information is not retained in the snoop-produced capture file.

Additionally, the SunScreen packet Screen is configurable to log network traffic for a variety of reasons, such as packets that were passed successfully, those that failed to match rules, those that arrived after session state expired, and so forth. This reason is recorded as an unsigned integer, commonly referred to as the why code. (See Appendix D, "Error Messages," for a complete table of these reasons in "Logged Packet Reasons.")

logdump displays these extended items and allows filtering based on these extended items.

The following is an example of what you type to restrict, based on interface, the logiface. It takes as its argument the name (or name prefix) of the interface desired. The name is compared in a case-insensitive manner. For example, to restrict log events to network traffic arriving on any qe network device, you would type:

% ... logiface qe ...

The following is an example of what you type to restrict based on the reason a packet was logged, the logwhy operator is provided. It takes as its argument a number representing a reason code described above. For example, to restrict log events to network traffic that was passed and logged, you would type:

% ... logwhy 1 ...

General Event Type Enhancements

In addition to network packet traffic, SunScreen logs can contain session summary events and extended log events. Each of these is represented by a different log record format.

Session summary events contain source and destination information regarding the session (for example, IP addresses and port numbers), plus ending statistics for the session. Extended log events are produced by various program components as previously described. logdump displays these new event types.

logdump allows discrimination of these types from network packet traffic events. The loglvl operator is provided to select network packet traffic, session summaries, authentication, and application events.

Log Record Format

The following is an example of what you type to restrict to network packet traffic events:

% ... loglvl pkt ...

Note -

The logiface and logwhy operators imply loglvl pkt.

The following is an example of what you type to restrict to session summary events:

% ... loglvl sess ...

Note -

In previous SunScreen releases, the sas_logdump program provided -S and -s options that provided a crude form of the loglvl sess feature. Those options are no longer supported.

The following is an example of what you type to restrict to authentication events:

% ... loglvl auth ...

The following is an example of what you type to restrict to application events:

 % ... loglvl app ...

The filtering mechanisms inherited from snoop related to IP addresses (for example, host, to, from, dst, src, and naked IP addresses and hostnames) have been extended to filter all event types that contain corresponding IP addresses. For example:

% ... from src host ...

matches packet, session, and extended events that originated from the given source host.

Similarly, the filtering mechanisms inherited from snoop related to TCP and UDP ports (for example, port, dstport and srcport) have been extended to filter all event types that relate to the corresponding services. For example:

% ... port svc ...

matches packet, session, and extended events that relate to the given service.

Extended Log Event Enhancements

The extended events added to the SunScreen log contain additional fields as previously described (severity code and program component name). The extended log mechanism has been generalized to allow a wide variety of events to be recorded in the log, both in SunScreen EFS 3.0 and into future releases. Because of the self-described syntax used, virtually any event can conceivably be added to the log in this manner.

logdump allows discrimination of extended events based on their severity code. The logsev operator provides this ability. The operand for logsev is one of the severity pseudonyms emerg, alert, crit, err, warn, note, info, or debug (these same designators are used to restrict the actual logging of these events). For example:

% ... logsev warn ...

matches extended events of a severity warning or greater.

logdump allows discrimination of extended events based on the name of the program component that logged them. The logapp operator performs this restriction. The operand for logapp is a string that is the name of a program component. For example:

% ... logapp ftpp ...

matches extended events for the FTP proxy.

Note -

The logsev and logapp operators imply a filter of ( loglvl auth or loglvl app ). All extended log events share some common optional attributes.

These attributes are optional because they only occur in log events where they make sense, but are common in the sense that they are handled in a consistent way. These attributes are:

Table 4-1 Optional Attributes


Attribute	Description
`sess_ID`	A session serial number, used to recognize various events that are related to each other.
`proto_ip`	IP protocol number (usu. 6 for TCP or UDP).
`src_ip`	IP source address.
`src_port`	IP source port number.
`dst_ip`	IP destination address.
`dst_port`	IP destination port number.
`reason`	Short description of the events mission in life.
`msg`	Generic message text.

Log Filtering Macros

For SunScreen EFS 3.0, log filters can be defined as named quantities. These are referred to as log macros.

Log macros are defined and stored in the registry (on the primary Screen) or they can be defined in a local registry on any Screen. Log macros defined in the registry of the primary Screen have the benefits of automatic propagation to secondary Screens that are enjoyed by all other SunScreen registry objects. This propagation affords uniform log filter availability and ease of common usage across a collection of managed Screens.

Log macros can also be defined in a registry-like facility that is local to each secondary Screen. This local macro capability is provided as a means to deal with emergency situations and other issues of expediency where the process of central macro definition and mass activation is unacceptable in the face of the conditions at hand. As a general practice, it is a good idea to collect such local macros back into the central registry as soon as practical for permanent storage and propagation.

Log macros are named using a global- and Screen-specific two-level scheme similar to other objects in SunScreen EFS 3.0. Evaluation mechanisms prefer a Screen-specific macro with a given name over a global one. Evaluation of macros occurs at the time of usage. (Users familiar with computer programming languages will recognize this as a traditional delayed name binding mechanism with dynamic scoping.)

Log macros also provide a bridge between the namespace of address and service objects defined in the SunScreen registry and their potential usage (as resolved to values) by the filtering facilities of logdump.

Note -

logdump filtering retains the hostname-to-address and service name-to-port number mapping mechanisms of snoop, namely, DNS, NIS, host and service tables defined for standard Solaris.

Log macros provide a way to access the name mappings of the registry in translating names to values.

Displaying and Creating Log Macros

Log macros are actually a derivative of the general SunScreen variable mechanism. Therefore, the variable naming and value structures exist for log macros, namely:

sys=Screen				(optional)
name=macroname
value="macrobody"
description="descriptive text"	(optional)
enabled | disabled			(default is enabled)

Log macros are configured in the registry using the logmacro edit sub-command of ssadm. For group-Screen installations, they are configured on the primary Screen.

The following is an example of what you type to display the definition of a non-Screen specific macro, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> logmacro print name=mail-only
NAME="mail-only" ENABLED VALUE="svc
smtp" 

DESCRIPTION="SMTP mail" ...

The following is an example of what you type to define a non-Screen specific macro, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> logmacro add name=pkts-only value="loglvl pkt" Description="only network packets"
edit> quit

The following is an example of what you type to define a macro for a specific Screen, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> logmacro add sys=Screenname name=SFO-routing value="port rip src SFO-routers" description="routing activity in SFO district"
edit> quit

Note -

Although, the output produced by print surrounds the value of each item in double quotes, these are only necessary on input to protect embedded spaces within the values of items. Also, although print outputs all tag names in capital letters (for example, NAME=), these tags are recognized in a case-insensitive manner on input (for example, name=, Name=, NAME= are equivalent.)

The following is an example of the message you see if you attempt to save without changing entities other than these types:

edit> savelock not held
failed (status 244)

This is a non-fatal message and you can simply quit the configuration editor.

Log macros are available for immediate use on the Screen whereupon they have been defined. It is not necessary to do an activate each time a log macro is changed to use it. However, to propagate log macro definitions from a primary Screen to secondaries, activation is necessary.

As previously indicated, it is also possible to create expediency log macros on any Screen. This is done using logmacro as a sub-command of ssadm (rather than a ssadm edit sub-command). The syntax of the rest of the usage is the same as given above.

The following is an example of what you type to display the definition of a non-Screen-specific macro, while logged in to the primary Screen:

admin% ssadm -r secondary logmacro print name=mail-only
NAME="mail-only" ENABLED VALUE="svc
smtp" 

DESCRIPTION="SMTP mail" ...

The following is an example of what you type to define a macro for a specific Screen, while logged in to the primary Screen:

admin% ssadm -r secondary logmacro add sys=slave name=SFO-routing value="port rip src SFO-routers" description="routing activity in SFO district"

Caution -

It is bad practice to define Screen-non-specific log macros on secondary Screens. In future SunScreen firewall releases, the ability to do so will be removed.

Log Macro Name and Body

The name of a log macro, as has been previously shown, consists of a name=macroname part, preceded by an optional sys=Screenname Screen-restriction part.

Unlike many objects in SunScreen, the macroname portion must be formulated as a simple identifier, rather than a more complicated general string. (A simple identifier begins with an ASCII alphabetic character or an underscore, followed by zero or ASCII alphanumeric characters or underscores.)

The macrobody (value part) of a log macro consists of a filtering expression suitable for logdump. It its simplest form, this is simply a string that can be used directly as filtering arguments.

However, the log macro expansion feature parses the value string looking for logdump operators that introduce address and service names and, finding same, attempts to resolve them from the SunScreen registry. So, for addresses, it looks for the operators host, to, from, between, dst, src and tries to resolve their operands in the address registry; if found therein, the operator-operand sequence is rewritten with the registry value for that address.

Similarly, for services, it looks for the operators port, dstport, and srcport and, if their operand resolves in the service registry, the operator-operand sequence is rewritten with the registry value.

Note -

In SunScreen EFS 3.0, the registry services expanded in this manner can only consist of TCP or UDP services; ranges of ports are allowed, but groups are disallowed as are services that use non-TCP non-UDP state engines.

Additionally, expansion looks for the operator macro and, if found, looks up the operand and replaces the operator-operand sequence with the named macros body.

From the discussion of the processing done on the macrobody string during evaluation, it should be evident why macro names must be simple identifiers. Similarly, expansion cannot handle addresses nor services from the registry that are not named with simple identifiers as well.

Listing Log Macros

Log macros in the primary registry can be displayed using the logmacro sub-command of ssadm edit. Individual macro definitions can be displayed. Also, all Screen-non-specific definitions, or all definitions specific to a Screen, or all definitions specific to any Screen, can be displayed. An abbreviated listing containing just the names of these last three classes of macros can also be generated.

The following is an example of what you type to display a specific macro definition, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> logmacro print name=mail-only
NAME="mail-only" ENABLED VALUE="svc
smtp" DESCRIPTION="SMTP mail"...
edit> logmacro print sys=secondary name=SFO-routing
SYS="secondary" NAME="SFO-routing"
VALUE="port rip src SFO-routers" DESCRIPTION="routing activity in
SFO district" ...

The following is an example of what you type to display all Screen-non-specific definitions, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> logmacro print
NAME="mail-only" ENABLED VALUE="svc
smtp" DESCRIPTION="SMTP mail" ...
NAME="pkts-only" ENABLED VALUE="loglvl
pkt" DESCRIPTION="only network packets" ...

The following is an example of what you type to display all definitions specific to a Screen, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> logmacro print sys=slave
SYS="slave" NAME="SFO-routing" VALUE="port
rip src SFO-routers" DESCRIPTION="routing activity in SFO district"
...

The following is an example of what you type to display all definitions specific to any Screen, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> logmacro print sys=
SYS="master" NAME="HQ-routing" VALUE="port
rip src HQ-routers" DESCRIPTION="routing activity in HQ district"
...
SYS="slave" NAME="SFO-routing" VALUE="port
rip src SFO-routers" DESCRIPTION="routing activity in SFO district"
...

The following is an example of what you type to produce name lists, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> logmacro names sys=
SYS="master" NAME="HQ-routing" VALUE="port
rip src HQ-routers" DESCRIPTION="routing activity in HQ district"
...
SYS="slave" NAME="SFO-routing" VALUE="port
rip src SFO-routers" DESCRIPTION="routing activity in SFO district"
...

The following is an example of what you type to display all Screen-non-specific names, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> logmacro names
NAME="mail-only"
NAME="pkts-only"

The following is an example of what you type to display all names specific to a Screen, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> logmacro names sys=slave
SYS="slave" NAME="SFO-routing"

The following is an example of what you type to display all names specific to any Screen, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> logmacro names sys=
SYS="master" NAME="HQ-routing"
SYS="slave" NAME="SFO-routing"

The following is an example of what you type to display a specific macro definition, while logged in to the primary Screen:

admin% ssadm -r secondary logmacro print name=mail-only
NAME="mail-only" ENABLED VALUE="svc
smtp" DESCRIPTION="SMTP mail" ...
admin% ssadm -r secondary logmacro print sys=slave name=SFO-routing
SYS="slave" NAME="SFO-routing" VALUE="port
rip src SFO-routers" DESCRIPTION="routing activity in SFO district"
...

The following is an example of what you type to display all Screen-non-specific definitions, while logged in to the primary Screen:

admin% ssadm -r secondary logmacro print
NAME="mail-only" ENABLED VALUE="svc
smtp" DESCRIPTION="SMTP mail" ...
NAME="pkts-only" ENABLED VALUE="loglvl
pkt" DESCRIPTION="only network packets" ...

The following is an example of what you type to display all definitions specific to a Screen, while logged in to the primary Screen:

admin% ssadm -r secondary logmacro print sys=secondary
SYS="slave" NAME="SFO-routing" VALUE="port
rip src SFO-routers" DESCRIPTION="routing activity in SFO district"
...

The following is an example of what you type to produce name lists, while logged in to the primary Screen:

admin% ssadm -r secondary logmacro names sys=secondary
SYS="slave" NAME="SFO-routing" VALUE="port
rip src SFO-routers" DESCRIPTION="routing activity in SFO district"
...

The following is an example of what you type to display all Screen-non-specific names, while logged in to the primary Screen:

admin% ssadm -r secondary logmacro names
NAME="mail-only"
NAME="pkts-only"

The following is an example of what you type to display all names specific to a Screen, while logged in to the primary Screen:

admin% ssadm -r secondary logmacro names sys=secondary
SYS="slave" NAME="SFO-routing"

Log Macro Usage

A log macro is utilized by expanding its value and by causing that expansion to be presented as a filter expression to a log get* or logdump command.

The following is an example of what you type to perform log macro expansion using logmacro as a sub-command to ssadm, consider the following, while logged in to Screen:

admin% ssadm -r Screen logmacro print
NAME="probed-ports" ENABLED VALUE="icmp
or dstport telnet or dstport rlogin or dstport rsh or dstport ftp
or srcport X11 or port adminweb"
admin% ssadm -r Screen logmacro print sys=
SYS="Screen" NAME="suspicious" ENABLED
VALUE="logwhy 256 logiface le0 ( not from trusted or to hidden )
macro probed-ports"

The above shows two macros defined. The first, probed-ports is Screen-non-specific and ostensibly defines services that are thought to be targets for initial probes leading to security attacks. The second, suspicious, is specific to Screen and contains a more complete macro for filtering potential probes; it restricts itself to packets logged because there was no rule found or they had source addresses that were illegal on their interface ("logwhy 256"), further to packets arriving on a specific (presumably outside) interface ("logiface le0"), yet further to packets originating from non-trusted hosts or targeted at hosts that are non-published ("not from trusted or to hidden"), and yet further to restrictions imposed by the macro "probed-ports".

Tip -

As a brief aside, the verb names,flat produces a list of names that are available for macro expansion on a particular Screen.

For example, while logged in to Screen, type:

admin% ssadm -r Screen logmacro names,flat
"probed-ports"
"suspicious"

Note -

Screen-specific issues of macros have been hidden, listing macro names as they are used by embedded macro references.

Assuming the following definitions have been created and activated for registry items:

edit> list Address
"abraham" HOST 1.2.3.4
"hidden" RANGE 129.9.9.0 129.9.9.255
"john" HOST 2.3.4.5
"martin" HOST 3.4.5.6
"trusted" GROUP { "abraham" "martin"
"john" } { }
edit> list Service
"rlogin" SIMPLE FORWARD "tcp" PORT
513
"rsh" SIMPLE FORWARD "tcp" PORT 514
"telnet" SIMPLE FORWARD "tcp" PORT
23
"X11" SIMPLE FORWARD "tcp" PORT 6000-6063

The following is an example of what you type to expand the given macro, while logged in to Screen:

admin% ssadm -r Screen logmacro expand suspicious
logwhy 256 logiface le0 ( not ( from
1.2.3.4 or from 2.3.4.5 or from 3.4.5.6 ) or to 129.9.9.0..129.9.9.255
) ( icmp or dstport 23 or dstport 513 or dstport 514 or ( srcport
20 or dstport 21 ) or srcport 6000..6063 or port adminweb )

This usage illustrates various expansion and resolution operations performed by expand. The clause "from trusted" has been replaced by the registry values for the GROUP "trusted". The clause "to hidden" has also been resolved to a registry RANGE, using the logdump syntax for IP address ranges "a.b.c.d..e.f.g.h."

The embedded macro reference "macro probed-ports" has been expanded. The clauses that can be resolved from the registry ("dstport telnet", "dstport rlogin", "dstport rsh", "dstport ftp", and "srcport X11"), have been expanded using registry values whereas clauses that were not found in the registry ("icmp" and "port adminweb") were left to be resolved by logdump itself. The "dstport ftp" clause further illustrates some special processing employed for that protocol, and the expansion of the "srcport X11" clause shows the logdump syntax for port ranges "x..y".

Note -

Resolution of SunScreen registry items performed by expand is made using those of the currently activated policy and for the Screen whereon the expand operation is executed.

The logmacro expand mechanism has been designed facilitate simple command-line usage in conjunction with the other log processing facilities of SunScreen.

The following is an example of what you type to employ the above macro to retrieve the suspicious items in the current log on the Screen and display them, while logged in to Screen:

admin% ssadm -r Screen log get `ssadm -r Screen logmacro expand suspicious` | ssadm logdump -V

Chapter 4 SunScreen EFS 3.0 Logs

Logging Limitations

Log File Locations

Configuring Traffic Log Size

Configuring the Global Default Log Size

Configuring the Log Size for a Specific Screen

Configuring Events to be Logged

Configuring Log Event Limiters

Log Retrieval and Clearing

Log Statistics

ssadm logstats Sub-Command

Log Inspection and Browsing

Log Filters and the logdump Command

logdump Extensions

Logged Network Packet Enhancements

General Event Type Enhancements

Log Record Format

Extended Log Event Enhancements

Log Filtering Macros

Displaying and Creating Log Macros

Log Macro Name and Body

Listing Log Macros

Log Macro Usage

`ssadm logstats` Sub-Command

Log Filters and the `logdump` Command

`logdump` Extensions