Chapter 11 Logging

Examination of logged packets is useful when you are trying to identify the causes of problems during network configuration or administration. You can also examine logs periodically for evidence of attempts to break into your network. This chapter contains information on:

• "Packet Logging"

• "Log File Locations"

• "Configuring Traffic Log Size"

• "Log Retrieval and Clearing"

• "Log Statistics"

• "Log Inspection and Browsing"

• "SunScreen welfmt Utility"

• "HTTP Proxy Header Logging"

• "Logged Network Packet Enhancements"

• "General Event Type Enhancements"

• "Log Filtering Macros"

Packet Logging

SunScreen provides flexible logging of packets. This means that each Screen can keep a log of its traffic as configured. In HA clusters, a log of the packets is kept on the Screen that passed or rejected the packets.

You can configure a Screen to log a packet when the packet 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.

Each system in a high availability (HA) cluster logs what that Screen passed or rejected, as well as local Screen events. Only the active Screen in an HA cluster logs packets, but even when an HA Screen is passive, some local events (such as becoming the active Screen) are logged.

Logging Limitations

The following limitations apply to logging:

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

• Only the active system logs packets.

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

  
  

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/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 consists of a number of files in a particular directory. Each Screen has a log file of its own.

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. These sizes are propagated to various Screens being managed during the normal activation process. The log file is resized on a particular Screen only when that Screen is restarted after the activation. 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. Activating the policy with the 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. Instructions for setting logsize (global and for a particular Screen) are included below.

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 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, which can only be configured using the configuration editor, is controlled by the variable LogSize. It contains the following items:

• prg=log

• name=LogSize

• value=size (in megabytes)

• description="descriptive text" (optional)

• enabled | disabled (default is enabled)

Examples: Setting or Displaying the Global Default Log File Size

Group Screen installations are configured on the primary Screen. To set the global default log file size to 250 Mbytes, while logged into the primary Screen:

admin% ssadm -r primary edit Initial
edit> vars add prg=log name=LogSize value=250 description="log size (MB)"

To display the global default log file size:

admin% ssadm -r primary edit Initial
edit> vars print prg=log name=LogSize
PRG="log" NAME="LogSize" ENABLED 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 if there are 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, and PRG are equivalent).

Configuring the Log Size for a Specific Screen

This section shows you how to set a log size for a particular Screen that is different from the global log size.

Examples: Displaying and Setting the Log File Size

To display the log file size for all Screens in an HA cluster:

admin% ssadm -r primary edit Initial
edit> list Screen 
scrn1 CDP ROUTING DNS
scrn2 CDP ROUTING DNS LOGSIZE 444

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

To set the log file size for a specific Screen (scrn1) to 200 MB:

admin% ssadm -r primary edit Initial
edit> add Screen scrn1 CDP ROUTING DNS LOGSIZE 200
edit> 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, or VPN. For each action, you can set the kind of packet logging that you want:

• LOG_NONE - Do not log packets

• LOG_SUMMARY - 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 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. This action is not used for stateless services such as ip all.

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

This option is not available for the DENY action (because no session was allowed).

Extended Events

Other events are logged besides packets and sessions. They are stored in an extended format. These other events arise from the following logging entities:

• auth - Authentication logic (in various other agents)

• edit - Configuration editor

• ftpp - The FTP proxy

• ha - The high-availability subsystem

• httpp - The HTTP proxy

• iked - The IKE daemon

• log - The logger itself

• smtpp - The SMTP proxy

• telnetp - The Telnet proxy

Each entity has a LogSeverity variable which limits the extent of its logging of noteworthy events based on the severity level of those events.

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

• name=LogSeverity - For all Screens

• sys=Screen name=LogSeverity - Screen-specific

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 with several levels of globality, within entities and/or Screens, and/or universally. The limiters serve to control logging situations where a particular rule is not yet known to the entity, or where no particular 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 control over events that can be attributed to a particular rule. Specifically, any rule-specific event of a severity of INFO or greater is 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 sizes shown in the table below apply to logged items (by type).

Level of Logging

Because the level of logging from a given program entity can be limited by the setting of the LogSeverity variable for that entity, a variable can be specific to a particular Screen (within a CMG group of centrally-managed Screens) or applicable to all Screens (those without a Screen-specific variable). If no variable is defined for a given entity, more general variables control such logging (again, on a per-Screen or non-Screen-specific basis). The search order for log limiter variables can be summarized as:

sys=Screenname prg=entityname name=LogSeverity




prg=entityname name=LogSeverity




sys=Screenname name=LogSeverity




name=LogSeverity

As initially configured, SunScreen contains log limiter variables for each program entity, as well as the non-Screen, non-entity-specific (global global) default. All are initially configured to the value info.

Log limiter variables are configured using the configuration editor.

Configuring Log Event Limiters

The log limiters are controlled by LogSeverity variables, which contain 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.)

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

Examples: Manipulating Log Limiters

Do the following while logged into the primary Screen.

To Display the global global  log limiter:

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

To display the global log limiter for authentication events:

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

To log more debugging information on a particular Screen for authentication events:

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 if there are 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.

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

Clearing a Screen's log does NOT free up any disk space. The disk space used by the log, up to the maximum log size, is maintained, to guarantee that there will always be room for the log data. Note also that the disk space used by a log may be slightly more (approximately sixteen megabytes) than the configured log size.

You can retrieve and postprocess logs on an automated basis. ( See the man page for sslogmgmt(1M) for details on automated log management.) 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 a feature installed by the SUNWsfwau package.

The table below shows the three subcommands for log.

Retrieval (get) of the log produces the (binary) log records on the standard output of ssadm. This can be redirected to a file or perhaps piped into other processes, such as ssadm logdump for viewing, further filtering, and so forth. The output stream from a log get* operation is manipulated with the piping and redirection capabilities of the shell that you are using on your Administration Station.

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.

Examples: get, clear, get_and_clear

The following are examples of working with the get, clear, and get_and_clear commands.

To get the log from a Screen you are logged into (primary or secondary) and store the filtered result in a local file:

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

See "Log Filters and the logdump Command" for information about filtering.

To simply clear the log:

admin% ssadm -r Screen log clear

To get the log, store the filtered result in a local file, and clear the log:

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

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

Here are examples of the get_and_clear and clear commands. To get and clear the log, setting the user designator as "ben":

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

To clear the log, setting the user designator as "Ben" and commenting that Ben should reset a counter or something after moving a file:

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

Log Statistics

You can inspect the current statistics of a Screen's log file from the administration GUI or by using the logstats subcommand of ssadm, as shown below.

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

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, 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 command) 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

Screen log filtering employs a common mechanism and language, regardless of the context in which it is used. This mechanism and language is embodied in the logdump command. The logdump command 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 routine log 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.

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. The examples in this section are 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.

Examples: logdump Command

To process (piped-in) records from the standard input:

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

To process local file log record input:

admin% ssadm logdump -i local_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:

admin%ssadm logdump -i input arg -o local_log_file [filter args] 

Omit the -o option to output readable text.

The formatting options for readable text are common to snoop; these are -v, -V, -t[r|a|d], and -xoffset[,length]. For more information, see snoop(1M) man page.

logdump Extensions

logdump is an extension of the standard snoop packet monitoring tool provided with the Solaris operating environment. Any expertise in the use of snoop is directly applicable to use of logdump.

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

logdump has been extended to provide for the special additional needs of SunScreen. 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 packets are logged (whycodes)

• 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 and service 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.

SunScreen welfmt Utility

The SunScreen welfmt utility reads a SunScreen binary log file and generates an ASCII log file in WebTrends Enhanced Log Format (WELF). This allows the WebTrends Firewall Suite (WFS) to analyze SunScreen log files and produce detailed reports on topics such as bandwidth usage, protocol distribution, email and Web activity, FTP transfers, and Telnet sessions.

WFS is a third-party product from WebTrends that provides a greater variety of visual log analysis tools. If it is already loaded on your system, ensure you are using Version 3.0 or later. For further details, see the WebTrends Web site. See also the ssadm-welfmt(1m)man page.

The following procedure, performed on a system with WFS installed, describes how to use the SunScreen welfmt utility to enable WFS to analyze your SunScreen log files. It also describes how to produce the WELF log file from a SunScreen binary log file.

The welfmt utility is included on the SunScreen 3.2 CD-ROM.

1. Use the SunScreen configuration editor to retrieve the SunScreen log file from your Screen and save it:

   # ssadm log get > binary-logfile

2. Run the welfmt utility with the output of step 1 as input and save the ASCII output:

   # ssadm welfmt -f your-Screen-name -i binary-logfile > output-file

3. Import the welfmt output file to the system with the WFS product installed.

HTTP Proxy Header Logging

The proxies in SunScreen 3.2 produce a number of log events which are useful to the WebTrends Firewall Suite (WFS), (via the welfmt utility.) However, the default set of HTTP protocol header items logged by the HTTP proxy do not, by default, include several header items which extend the usefulness of the reports generated by WFS.

For backward-compatibility reasons, the default set of HTTP header items logged remains largely as in previous releases of SunScreen. To accommodate the needs of WFS users, the HTTP proxy has been augmented to enable additional header items to be mapped into its log events.

Configuration of this mapping facility is controlled by a pair of variables, one to control HTTP request headers, the other to control HTTP response headers. The requests header mappings are tailored by:

• sys=Screen (optional)

• prg=httpp

• name=LogRqsts

• values={ hdrmaps }

• description="descriptive text"

• enabled | disabled (as initially configured, it is disabled)

The response header mappings are tailored by:

• sys=Screen (optional)

• prg=httpp

• name=LogRsps

• values={ hdrmaps }

• description="descriptive text"

• enabled | disabled (as initially configured, it is disabled)

The hdrmaps portion is a list of one or more of the following:

• group="WELF"

• name="namestr"

• name="!namestr"

• prefix="prefixstr"

• prefix="!prefixstr"

• suffix="suffixstr"

• suffix="!suffixstr"

group="WELF" enables all headers useful to WFS (either request or response, depending upon the variable in which they appear). Other forms specify the full header names (name=...), header prefix strings (prefix=...), or header suffix strings (suffix=...) to map on an individual basis. Forms with an exclamation point (!) represent negating the sense of the match.

Mappings are processed in the order in which they occur in the values={ ... } list. Specific matches should appear before more general ones.

Enabling a mapping causes the header(s) which match to be promoted into the NOTICE log events, thus retaining their values in the SunScreen log.

Both variables -- LogRqsts and LogRsps -- are pre-defined. If you display their install-time values, you see:

admin% ssadm -r primary edit Initial
edit> vars print prg=httpp name=LogRqsts
PRG="httpp" NAME="LogRqsts" DISABLED VALUES={ group="WELF" } 
 DESCRIPTION="request headers to log"
edit> vars print prg=httpp name=LogRsps
PRG="httpp" NAME="LogRsps" DISABLED VALUES={ group="WELF" } 
 DESCRIPTION="response headers to log"

Note that the variables must be changed to ENABLED to log headers optimal to WFS reporting.

Logged Network Packet Enhancements

SunScreen logs contain 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 a snoop-produced capture file.

Additionally, you can configure a 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, etc. The 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 the table below.

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

The table below contains examples of the logdump filters that you can use to restrict the display of 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:

admin% ... ssadm log get from src_host > out_log

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:

admin% ... ssadm log get port svc > out_log

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 enable a wide variety of events to be recorded in the log. Because of the self-described syntax used, virtually any event can 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:

admin% ssadm -r Screen log get | ssadm logdump -i- 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:

admin% ssadm -r Screen log get | ssadm logdump -i- 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 the table below.

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 are automatically propagated to secondary Screens in the same way as 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 for emergency situations and other cases where central macro definition and mass activation is unacceptable. 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.

If you are familiar with computer programming languages you 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 host name-to-address and service name-to-port number mapping mechanisms of snoop--namely, DNS, NIS, host, and service tables defined for Solaris software.

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=Screenname (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.

You do not have to save a log macro to use it; it is saved when it is created. However, to propagate log macro definitions from a primary Screen to secondaries, you must activate the configuration.

Examples: Log Macros on the Primary Screen

The following are examples of using log macros while logged into the primary Screen.

To display the definition of a non-Screen specific macro:

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

To define a non-Screen specific macro:

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

To define a macro for a specific Screen:

admin% ssadm -r primary edit Initial
edit> logmacro add sys=Screenname name=SFO value="port SFO" description="routing SFO" 
edit> quit

Although, the output produced by print surrounds the value of each item in double quotes, these are only necessary on input if there are 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.)

You can create expediency log macros on any Screen 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.

Examples: Log Macros on the Secondary Screen

The following are examples of using log macros while logged into the secondary Screen.

To display the definition of a non-Screen-specific macro:

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

To define a macro for a specific 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 log macros on secondary Screens which are not Screen-specific.

Log Macro Name and Body

The name of a log macro 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 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. 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. You can generate an abbreviated listing that contains just the names of these last three classes of macros.

Examples: Macro Definitions for the Primary Screen

The following are examples of displaying definitions while logged into the primary Screen.

To display two specific macro definitions:

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
SYS="secondary" NAME="SFO" VALUE="port SFO" DESCRIPTION="routing SFO" ...

To display all Screen-nonspecific definitions:

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

To display all definitions specific to a Screen:

admin% ssadm -r primary edit Initial
edit> logmacro print sys=secondary
SYS="secondary" NAME="SFO" VALUE="port SFO" DESCRIPTION="routing SFO" ...

To display all definitions specific to any Screen:

admin% ssadm -r primary edit Initial
edit> logmacro print sys=
SYS="primary" NAME="HQ-routing" VALUE="port HQ-routers" DESCRIPTION="HQ routing" ...
SYS="secondary" NAME="SFO-routing" VALUE="port SFO" DESCRIPTION="routing SFO" ...

To display all Screen-nonspecific names:

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

To display all names specific to a Screen:

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

To display all names specific to any Screen:

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

Examples: Macro Definitions for the Secondary Screen

The following are examples of displaying definitions while logged into the secondary Screen.

To display two specific macro definitions:

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 SFO" DESCRIPTION="routing SFO" ...

To display all Screen-nonspecific definitions:

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

To display all definitions specific to a Screen:

admin% ssadm -r secondary logmacro print sys=secondary
SYS="secondary" NAME="SFO-routing" VALUE="port SFO" DESCRIPTION="routing SFO" ...

The following is an example of what you would type to produce name lists:

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

To display all Screen-nonspecific names:

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

To display all names specific to a Screen:

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

Log Macro Usage

To use a log macro, you expand its value and cause 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"

Two macros are defined. The first macro, probed-ports, is Screen-nonspecific and ostensibly defines services that are thought to be targets for initial probes leading to security attacks. The second macro, suspicious, is specific to a Screen and contains a more complete macro for filtering potential probes. It restricts itself to:

• Packets logged because no rule was found or 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 -

  The verb names,flat produces a list of names that are available for macro expansion on a particular Screen. For example, while logged into a 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

To expand a given macro, while logged into a 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.

To employ the above macro to retrieve the suspicious items in the current log on the Screen and display them, while logged into the Screen:

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