Chapter 11 Logging

This chapter contains information on:

• "Packet Logging"

• "Log File Locations"

• "Configuring Traffic Log Size"

• "Log Retrieval and Clearing"

• "Log Statistics"

• "Log Inspection and Browsing"

• "Logged Network Packet Enhancements"

• "General Event Type Enhancements"

• "Log Filtering Macros"

Packet Logging

SunScreen provides flexible logging of packets. This means that each primary and secondary Screen keeps a log of its traffic. Logs of the packets are kept on the Screen that passed or rejected the packets.

You can configure Screen to log a packet when it matches a rule or when it does not. Most frequently, packets matching DENY rules or packets that are dropped because they do not match any rule are logged. The action defined in a rule controls whether a packet is logged and what information about the packet is recorded.

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

Each machine in an high availability (HA) cluster logs what that system passed or rejected, as well as any locally processed nonpacket events.

The active Screen in an HA cluster will log packets. As log entries become more extended, such events as nonpacket and nonsession entries in the logs of the passive Screens appear.

Logging Limitations

The following limitations apply to logging:

1. 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.

1. Decrypted packets are logged, but SKIP certificate IDs are not logged.

2. Only the active system logs packets.

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

Save Is Not Required With Certain Common Objects

It is not necessary to type save before quit if only authuser, adminuser, proxyuser, logmacro, or vars entities are altered. The following is an example of the nonfatal message you see if you attempt to save without changing entities other than these types. You can simply quit the configuration editor:

edit> save
lock not held failed (status 244)

These items are available for immediate use on the Screen where they have been defined. It is not necessary to activate each change in a log macro to use it. However, to propagate log macro definitions from a primary Screen to secondaries, you must activate the configuration.

Log File Locations

SunScreen stores its log files in the following locations:

• The SunScreen 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

You can configure the size of the area used to log packet traffic, session and other events. The log actually consists of a number of files in a particular directory. Each Screen has a log file of its own, and you can specifically configure the size of the log file on each Screen.

You establish the size of the log files in much the same way as other configuration items, and these sizes are propagated to various Screens being managed during the normal activation process. 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.

You should change the size of the log file when you are configuring your policies just after installing the Screen. You must have activated the policy with the new log sizes, but activating the policy with then new log sizes does not resize the log files. The log file on a particular Screen is only resized when that Screen is restarted. When the Screen is restarted, it uses the policy that was the last currently active one.

Setting the size of the log file does not cause the file system to allocate space for storing the log immediately. Competing users of the file system on which the log file resides should, therefore, not be allowed to consume this space. Even when the log has filled and begins to reuse file-system space, the maximum amount of file-system 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, Command-Line Reference.)

Group-Screen installations are configured on the primary Screen.

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

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

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

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

The following is an example of what you would 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)"

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).

Configuring the Log Size for a Specific Screen

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

You configure the global log size through the command line (see Appendix B, Command-Line Reference). It is controlled by the variable LogSize.

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

admin% ssadm -r primary edit Initial
edit> 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 would 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 20edit> save
edit> quit

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

Configuring Events to be Logged

Logs contain three basic types of events:

• Network traffic (packet)

• Network session summaries

• Extended events

Network Traffic (Packet)

You can set the action for each rule to be ALLOW, DENY, ENCRYPT, SECURE. For each action, you can set the kind of packet logging that you want:

• LOG_NONE - Do not log packets.

• LOG_SUMMAR - Records the first 40 bytes of the packet in the log.

• LOG_DETAIL - Records the complete packet in the log.

Network Session Summaries

You can set the action to the LOG_SESSION in a rule so that it records information about the session in the log. The information saved consists of the source and destination addresses and ports (if applicable), the amount of data being sent in each direction, and the length of the session. It is not used for stateless services such as ip all. You do this using the option LOG_SESSION.

The SESSION setting does not log packet content. Each basic protocol (for example, IP, UDP, TCP) logs statistics related to session as they complete

This option is not available for the DENY action

Extended events

In addition to logging of packets and sessions, other events are logged; these are stored in an extended format. Such other events arise from the following logging entities:

• auth - Au the tic at ion logic (in various other agents)

• edit - Configuration editor

• ftpp - The FTP proxy

• httpp - The HTTP proxy

• log - The logger itself

• smtpp - The SMTP proxy

• telnetpp - The Telnet proxy

Each entity has a var variable to limit the severity of logged items. These variables are named:

• prg=entity--the default for all Screens.

• sys=Screenentity name=LogSeverity--for a specific Screen

In addition, there exist default limiters as catchall for unnamed entities:

• name=LogSeverity

• sys=Screeny (for all Screens or Screen-specific, respectively).

The LogSeverity variables take text strings as their value. The value functions as a not-more-detail-than limiter and is similar to the functionality of the Solaris' syslog command. The text values are:

• NONE

• ALERT

• CRIT

• ERR

• WARN

• NOTE

• INFO

• DEBUG

These limiter variables operate globally (within the entities and Screens to which their scope applies). This deals with logging situations where a particular rule is not yet known or where no rule applies.

In addition, the effect of the per-rule DETAIL, SUMMARY, and SESSION attributes is overridden by some of these logging entities. This override allows for finer-grain control over events which can be attributed to a particular rule. Specifically, any rule-specific event of a severity of INFO or greater will be logged if that rule has (packet or session) logging enabled.

Size of Logged Items

All items in the logs have a common, 24-byte header. After this header, the following sizes apply to logged items (by type), shown in TABLE 11-1.

Level of Logging

For a given program component, you can specify the level of logging. You do this 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 (that is, a component that is not specific) variable controls otherwise unlimited logging. 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=LogSeverity
prg=programname name=LogSeverity
sys=Screenname name=LogSeverity
name=LogSeverity

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

You can only configure events to be logged using the command line.

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=LogSeverity

• value=severityname (emerg,alert,...,debug)

• description=descriptive text (optional)

• enabled | disabled (The default is enabled.)

You can only configure the LogSeverity variables using the command line interface (see Appendix B, Command-Line Reference). You configure group-Screen installations on the primary Screen.

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

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

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

admin% ssadm -r primary edit Initial
edit> 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 would type to log more (debugging) information on a particular Screen for authentication events, while logged in to the primary Screen:

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

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). Finally, the VALUE string for the LogSeverity variable is likewise processed in a case-insensitive manner.

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

Log Retrieval and Clearing

A Screen's log is retrieved and can be cleared using the log subcommand of ssadm. Filtering can be applied by the Screen during retrieval, reducing the content of the log retrieved (see "Log Inspection and Browsing").

You can retrieve and postprocess 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.

TABLE 11-2 show the thee subcommands for log.

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.

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 would type to get the log from a given (primary or secondary) Screen to store in a local file:

admin% ssadm -r Screen log get [filterargs] >local_log_file

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

admin% ssadm -r Screen log get_and_clear [filterargs] >local_log_file

The following is an example of what you would 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 would type to get and clear the log, setting this designator:

admin% ssadm -r Screen log -U "ben" get_and_clear [filterargs]>local_file

The following is an example of what you would 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 Screen's log file can be inspected in the administration GUI-based log browser.

These same statistics are also visible using the logstats subcommand of ssadm.

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 Subcommand

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

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

Log size 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.

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.

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 Screen's active log file can be browsed in either a historical or live mode. 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 a Screen's logs employs a common filtering mechanism and language, regardless of the context in which it is used. These are 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 environment.

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, predefined filters can be employed to simplify and regularize routinelog processing tasks.

The general usage for logdump is as a subcommand 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.

Remember that although logdump is used directly as an ssadm subcommand, 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 would 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 would type to process local file log record input:

% ssadm logdump -ilocal_log_file
[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 -i input arg
-o local_log_file
[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 environment. 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 and 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 that it is not involved in decisions as to what SunScreen logs. (Rules and variables previously described provide this control.) snoop is often used to filter network input during the process of capture or direct display. logdump serves as a means to postprocess log file content only.

SunScreen logs and snoop-captured files are not interoperable.

Logged Network Packet Enhancements

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

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, you can configure the packet Screen to log network traffic for a variety of reasons, such as packets that 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.)

logdump displays these extended items and allows filtering based on these extended items as shown in TABLE 11-3.

General Event Type Enhancements

In addition to network packet traffic, 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

TABLE 11-4 contains examples of the filters that you can use to restrict various events.

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 that are 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 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.

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. They are common in the sense that they are handled in a consistent way. These attributes are shown in TABLE 11-5.

Log Filtering Macros

For SunScreen, 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. 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.

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 subcommand of ssadm. For group-Screen installations, they are configured on the primary Screen.

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

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

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

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

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

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

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.)

It is also possible to create expediency log macros on any Screen. This is done using logmacro as a subcommand of ssadm (rather than an ssadm edit subcommand). The syntax of the rest of the usage is the same as given above.

The following is an example of what you would type to display the definition of a non-Screen-specific macro, while logged in to the secondary 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 would type to define a macro for a specific Screen, while logged in to the secondary Screen:

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

Do not define Screen-nonspecific log macros on secondary Screens.

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 they are found, 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. If their operand resolves in the service registry, the operator-operand sequence is rewritten with the registry value.

In SunScreen, 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 macro's 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 or 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 subcommand of ssadm edit. Individual macro definitions can be displayed. Also, all Screen-nonspecific 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 would type to display two specific macro definitions, while logged in to the primary Screen:

admin% ssadm -r primary edit Initial
edit> 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 would type to display all Screen-nonspecific definitions, while logged in to the primary Screen:

admin% ssadm -r primary edit Initial
edit> 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 would type to display all definitions specific to a Screen, while logged in to the primary Screen:

admin% ssadm -r primary edit Initial
edit> logmacro print sys=secondary
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 would type to display all definitions specific to any Screen, while logged in to the primary Screen:

admin% ssadm -r primary edit Initial
edit> logmacro print sys=
SYS="primary" NAME="HQ-routing" VALUE="port
rip src HQ-routers" DESCRIPTION="routing activity in HQ district" ...
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 would type to display all Screen-nonspecific names, while logged in to the primary Screen:

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

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

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

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

admin% ssadm -r primary edit Initial
edit> logmacro names sys=
SYS="primary" NAME="HQ-routing"
SYS="secondary" NAME="SFO-routing"

The following is an example of what you would type to display two specific macro definitions, while logged in to the secondary 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=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 would type to display all Screen-nonspecific definitions, while logged in to the secondary 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 would type to display all definitions specific to a Screen, while logged in to the secondary Screen:

admin% ssadm -r secondary logmacro print sys=secondary
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 would type to produce name lists, while logged in to the secondary Screen:

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

The following is an example of what you would type to display all Screen-nonspecific names, while logged in to the secondary Screen:

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

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

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

Log Macro Usage

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

To introduce examples of log macro expansion using logmacro as a subcommand to ssadm, the first example shows the defined values to two macros as rendered by ssadm logmacro print:

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 examples above show two macros defined. The first, probed-ports is Screen-nonspecific 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 no rule was found

• Packets that had source addresses that were illegal on their interface (logwhy 256)

• Packets arriving on a specific (presumably outside) interface (logiface le0)

• Packets originating from untrusted hosts or targeted at hosts that are unpublished (not from trusted or to hidden)

• Restrictions imposed by the macro "probed-ports".

  ---

  Tip -

  As an 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"

  ---

This hides Screen-specific issues of macros and lists macro names as they are used by embedded macro references.

Assume that 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 would 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. 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.

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 to facilitate simple command-line usage in conjunction with the other log processing facilities of SunScreen.

The following is an example of what you would 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 -i-