unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 nettl(1M)							   nettl(1M)




 NAME
      nettl - control network tracing and logging

 SYNOPSIS
      /usr/sbin/nettl -start

      /usr/sbin/nettl -stop

      /usr/sbin/nettl -firmlog 0|1|2 -card dev_name ...

      /usr/sbin/nettl -log class ... -entity subsystem ...

      /usr/sbin/nettl -status [log |trace |all]

      /usr/sbin/nettl -traceon kind ... -entity subsystem ...
	   [-card dev_name ...] [-file tracename] [-m bytes] [-size portsize]
	   [-tracemax maxsize] [-n num_files]

      /usr/sbin/nettl -traceoff -entity subsystem ...

 DESCRIPTION
      The nettl command is a tool used to capture network events or packets.
      Logging is a means of capturing network activities such as state
      changes, errors, and connection establishment.  Tracing is used to
      capture or take a snapshot of inbound and outbound packets going
      through the network, as well as loopback or header information.  A
      subsystem is a particular network module that can be acted upon, such
      as ns_ls_driver, or X25L2.  nettl is used to control the network
      tracing and logging facility.

      Except for the -status option, nettl can be used only by users who
      have an effective user ID of 0.

    Options
      nettl recognizes the following options, which can be used only in the
      combinations indicated in SYNOPSIS.  Some option and argument keywords
      can be abbreviated as described below.  All keywords are case-
      insensitive.

      -start	     (Abbr.: -st)
		     Used alone without other options.

		     Initialize the tracing and logging facility, start up
		     default logging, and optionally start up console
		     logging.  Logging is enabled for all subsystems as
		     determined by the /etc/nettlgen.conf file.	 Log
		     messages are sent to a log file whose name is
		     determined by adding the suffix .LOG00 to the log file
		     name specified in the /etc/nettlgen.conf configuration
		     file.  Console logging is started if console logging
		     has been configured in the /etc/nettlgen.conf file.



 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 nettl(1M)							   nettl(1M)




		     See nettlconf(1M) and nettlgen.conf(4) for an
		     explanation of the configuration file.  If the log file
		     (with suffix) already exists, it is opened in append
		     mode; that is, new data is added to the file.  The
		     default name is /var/adm/nettl (thus logging starts to
		     file /var/adm/nettl.LOG00).  See "Data File Management"
		     below for more information on how the log file is
		     handled.

		     A nettl -start command is performed during system
		     startup if the NETTL variable in the
		     /etc/rc.config.d/nettl file has a value of 1.

		     Note: It is strongly recommended that the tracing and
		     logging facility be turned on before any networking is
		     started and remain on as long as networking is being
		     used.  Otherwise, information about disasters will be
		     lost.  To minimize the impact on the system, all
		     subsystems can be set with the -log option to capture
		     only disaster-class log messages.

      -stop	     (Abbr.: -sp)
		     Used alone without other options.

		     Terminate the trace/log facility.	Once this command is
		     issued, the trace/log facility is no longer able to
		     accept the corresponding trace/log calls from the
		     network subsystems.

		     Note: See note for the -start option.

      -card dev_name ...
		     (Abbr.: -c)
		     This option is required by the X.25 subsystems; it is
		     optional for other subsystems.  Some subsystems do not
		     support this option.

		     Limit the trace information gathered to only the data
		     that comes from the specified network interface card.
		     More than one dev_name can be specified at a time in
		     order to trace multiple network interfaces.

		     dev_name specifies a device which corresponds to a
		     network interface card that has been installed and
		     configured.  It can be either an integer representing
		     the network interface, or the device file name of the
		     network interface.	 Some subsystems do not support both
		     types of dev_name.	 For example, the X25 subsystems
		     require that dev_name be a device file name.  The
		     product documentation for the subsystems should explain
		     if the -card option is applicable and how to choose an



 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 nettl(1M)							   nettl(1M)




		     appropriate dev_name.

		     If dev_name is not an integer it is assumed to be a
		     device file name.	The path prefix /dev/ will be
		     attached in front of dev_name if it is not an absolute
		     path name to form the device file name, /dev/dev_name.
		     dev_name must refer to a valid network device file.

      -entity all
      -entity subsystem ...
		     (Abbr.: -e)

		     Limit the action of -log, -traceoff, or -traceon to the
		     specified protocol layers or software modules specified
		     by subsystem.

		     The number and names of subsystems on each system are
		     dependent on the products that have been installed.
		     Use the command nettlconf -status to obtain a full
		     listing of supported subsystems and the products that
		     own them.

		     Examples of OSI subsystems:

			  acse_pres	   ftam_init	    mms
			  asn1		   ftam_resp	    network
			  cm		   ftam_vfs	    ots
			  em		   ftp_ftam_gw	    transport
			  ftam_ftp_gw	   hps		    ula_utils

		     Examples of LAN subsystems:

			  ns_ls_driver	   ns_ls_loopback   ns_ls_ni
			  ns_ls_icmp	   ns_ls_netisr	    ns_ls_tcp
			  ns_ls_igmp	   ns_ls_nfs	    ns_ls_udp
			  ns_ls_ip	   ns_ls_nft	    ns_ls_x25

		     Two X.25-specific subsystems are used for tracing only:

			  X25L2		   X25L3

      -file tracename
		     (Abbr.: -f)
		     Used with the first -traceon option only.

		     The first time the -traceon keyword is used, it
		     initializes tracing, creating a file tracename.TRC0
		     which receives the binary tracing data.  If a trace
		     file of the name tracename.TRC0 already exists the
		     binary trace data is appended to the end of the file.




 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 nettl(1M)							   nettl(1M)




		     To start a fresh trace file, first turn off tracing
		     then turn it back on again using a different tracename.
		     See "Data File Management" below for more information
		     on file naming.

		     If -file is omitted, binary trace output goes to
		     standard output.  If standard output is a terminal
		     device, an error message is issued and no tracing is
		     generated.

      -firmlog 0|1|2 (Abbr.: -fm)
		     Requires the -card option.
		     Series 800 and X.25 only.

		     Set the X.25/800 interface card logging mask to level
		     0, 1, or 2.  The default level is 0.  The X.25/800
		     interface logs a standard set of messages.	 A level of
		     1 specifies cautionary messages as well as the default
		     messages.	A level of 2 specifies information messages
		     in addition to the cautionary and default messages.
		     This option is recognized only by the ns_ls_x25
		     subsystem.

      -log class ... (Abbr.: -l)
		     Requires the -entity option.

		     Control the class of log messages that are enabled for
		     the subsystems specified by the -entity option.

		     class specifies the logging class.	 Available classes
		     are:

			     Full	Abbr.	Mask
			  __________________________
			  informative	  i	 1
			  warning	  w	 2
			  error		  e	 4
			  disaster	  d	 8

			  informative	      Describes routine operations
					      and current system values.

			  warning	      Indicates abnormal events
					      possibly caused by subsystem
					      problems.

			  error		      Signals an event or condition
					      which was not affecting the
					      overall subsystem or network
					      operation, but may have caused
					      an application program to



 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000






 nettl(1M)							   nettl(1M)




					      fail.

			  disaster	      Signals an event or condition
					      which did affect the overall
					      subsystem or network
					      operation, caused several
					      programs to fail or the entire
					      node to shut down.

		     Classes can be specified as keywords or as a single
		     numeric mask depicting which classes to log.  The mask
		     is formed by adding the individual masks of the log
		     classes.  If you choose to indicate several classes at
		     once, be sure to separate each log class with a space.

		     disaster logging is always on.  The default logging
		     classes for each subsystem is configured into the
		     configuration file, /etc/nettlgen.conf.  When the
		     tracing/logging facility is started, the information in
		     the configuration file is read and subsystems are
		     enabled for logging with the specified classes.  To
		     change the log class, use the
		     "nettl -log class -entity subsystem" command with a new
		     log class value.  If desired, the command can be run
		     for different log classes and different entities.

      -m bytes	     Specify the number of bytes (bytes) of each trace
		     record to trace.  This option allows the user to
		     specify the number of bytes to be captured in the trace
		     packet.  The user may prefer not to capture an entire
		     PDU trace, such as when the user is only interested in
		     the header.

		     The maximum value for bytes is 2000.  By default, the
		     entire packet is traced.  A value of 0 will also cause
		     the entire packet to be traced.  This option currently
		     applies only to kernel subsystems.

      -size portsize (Abbr.: -s)
		     Used with first -traceon option only.

		     Set the size in kilobytes (KB) of the trace buffer used
		     to hold trace messages until they are written to the
		     file.  The default size for this buffer is 68 KB.	The
		     possible range for portsize is 1 to 1024.	Setting this
		     value too low increases the possibility of dropped
		     trace messages from fast subsystems.

      -status log
      -status trace




 Hewlett-Packard Company	    - 5 -   HP-UX Release 11i: November 2000






 nettl(1M)							   nettl(1M)




      -status [all]  (Abbr.: -ss)
		     Used alone without other options.

		     Report the tracing and logging facility status.  The
		     facility must be operational, that is, nettl -start has
		     been completed.  The additional options define the type
		     of trace or log information that is to be displayed.
		     The default value is all.

			  log	    Log status information

			  trace	    Trace status information

			  all	    Trace and log status information

      -tracemax maxsize
		     (Abbr.: -tm)
		     Used with first -traceon option only.

		     Tracing uses a circular file method such that when one
		     file fills up, another file is used.  The number of
		     trace files that can exist on a system at any given
		     time can be specified using the -n option.	 See "Data
		     File Management" below for more information on file
		     behavior.

		     maxsize specifies the maximum size in kilobytes (KB) of
		     any two trace files combined.  Therefore, the maximum
		     size of each trace file will be approximately half of
		     maxsize kilobytes (KB).  The default value for the
		     combined file sizes is 1000 KB.  The possible range for
		     maxsize is 100 to 99999.

      -n num_files   Used with first -traceon option only.

		     Specifies the number of trace files that can exist on a
		     system at any given time.	However, nettl can reduce
		     the number of trace files depending on the available
		     disk space. If the option is not specified, the default
		     value is two trace files.

      -traceoff	     (Abbr.: -tf)
		     Requires the -entity option.

		     Disable tracing of subsystems specified by the -entity
		     option.  If all is specified as an argument to the
		     -entity option, all tracing is disabled.  The trace
		     file remains, and can be formatted by using the netfmt
		     command to view the trace messages it contains (see
		     netfmt(1M)).




 Hewlett-Packard Company	    - 6 -   HP-UX Release 11i: November 2000






 nettl(1M)							   nettl(1M)




      -traceon all
      -traceon kind ...
		     (Abbr.: -tn)
		     Requires the -entity option.  The -card option is
		     required for X.25 subsystems.  Other options are not
		     required.

		     Start tracing on the specified subsystems.	 The tracing
		     and logging facility must have been initialized by
		     nettl -start for this command to have any effect.	The
		     default trace file is standard output; it can be
		     overridden by the -file option.  If standard output is
		     a terminal device, then an informative message is
		     displayed and no trace data is produced.

		     When tracing is enabled, every operation through the
		     subsystems is recorded if the kind mask is matched.

		     kind defines the trace masks used by the tracing
		     facility before recording a message.  If -traceon all
		     is specified, all trace masks are enabled.	 kind can be
		     entered as one or several of the following keywords or
		     masks:

			  keyword      mask		keyword	      mask
			  _____________________	       ______________________
			  hdrin	    0x80000000		state	   0x04000000
			  hdrout    0x40000000		error	   0x02000000
			  pduin	    0x20000000		logging	   0x01000000
			  pduout    0x10000000		loopback   0x00800000
			  proc	    0x08000000

			  hdrin		 Inbound Protocol Header.

			  hdrout	 Outbound Protocol Header.

			  pduin		 Inbound Protocol Data Unit
					 (including header and data).

			  pduout	 Outbound Protocol Data Unit
					 (including header and data).

			  proc		 Procedure entry and exit.

			  state		 Protocol or connection states.

			  error		 Invalid events or condition.

			  logging	 Special kind of trace that contains
					 a log message.




 Hewlett-Packard Company	    - 7 -   HP-UX Release 11i: November 2000






 nettl(1M)							   nettl(1M)




			  loopback	 Packets whose source and
					 destination system is the same.

		     For multiple kinds, the masks can be specified
		     separately or combined into a single number.  For
		     example, to enable both pduin and pduout (to trace all
		     packets coming into and out of the node) use either
		     pduin pduout or 0x10000000 0x20000000 or the
		     combination 0x30000000.

		     Not all subsystems support all trace kinds.  No error
		     is returned if a given subsystem does not support a
		     particular trace kind.

		     If a -traceon is issued on a subsystem that is already
		     being traced, the tracing mask and optional values are
		     changed to those specified by the new command, but the
		     new -file, -size, and -tracemax options are ignored and
		     a message is issued.

		     If -entity all is specified, all recognized subsystems
		     are traced except X.25-specific subsystems.  To turn on
		     tracing for X.25, use the command

			  nettl -traceon kind -e x.25_subsys -card dev_name

		     where the value of x.25_subsys is X25L2 or X25L3.

    Data File Management
      Data files created by the tracing and logging facility require special
      handling by the facility that the user must be aware of.	When files
      are created, they have the suffix .LOG00 or .TRC00 appended to them,
      depending on whether they are log or trace files, respectively.  This
      scheme is used to keep the files distinct for cases where the user
      specifies the same name in both places.  Also, the files implement a
      type of circular buffer, with new data always going into the file
      appended with .LOG00 or .TRC00.  When a logname.LOG00 or
      tracename.TRC00 file is full, each log or trace is renamed to the next
      higher number in its sequence; that is, a file with sequence number N
      is renamed as a file with sequence number N+1 and a new file named
      logname.LOG00 or tracename.TRC00 is created. The number of files that
      can exist simultaneously on the system can be specified by the -n
      option.

	   Note: The file name prefix (logname or tracename) specified by
	   the user must not exceed eight characters so that the file name
	   plus suffix does not exceed fourteen characters.  Longer names
	   are truncated.  To see the actual name of the trace or log file,
	   use the nettl -status all command.





 Hewlett-Packard Company	    - 8 -   HP-UX Release 11i: November 2000






 nettl(1M)							   nettl(1M)




    Console Logging
      Console logging is used to display significant log events on the
      system console.  The values in the /etc/nettlgen.conf file determine
      if console logging is to be started and the entries in the
      /var/adm/conslog.opts file determine what log messages will be
      reported to the console.	The nettlconf command can be used to
      configure and maintain the information in the /etc/nettlgen.conf file
      (see nettlconf(1M)).  If changes are made to these files, nettl must
      be stopped and restarted for the new information to take effect.

      All log messages written to the console as a result of this
      configuration information are in a special short form.  If more
      information is desired on the console, the netfmt formatter can be
      used to direct output to the console device.  This may be most useful
      in an X windows environment.

      Console logging may be disabled if conservation of system resources is
      valued more than notification of log events.

 EXTERNAL INFLUENCES
    International Code Set Support
      Single- and multibyte character code sets are supported in data;
      single-byte character code sets are supported in file names.

 EXAMPLES
      1.   Initialize the tracing/logging facility:

		nettl -start

	   (See note for the -start option.)

      2.   Display the status of the tracing/logging facility.

		nettl -status all

      3.   Change log class to error and warning for all the subsystems.
	   disaster logging is always on for all subsystems.

		nettl -log e w -e all

      4.   Turn on inbound and outbound PDU tracing for the transport and
	   session (OTS/9000) subsystems and send binary trace messages to
	   file /var/adm/trace.TRC0.

		nettl -traceon pduin pduout -entity transport session \
		     -file /var/adm/trace

      5.   Turn on outbound PDU tracing for X.25 level two, and subsystem
	   ns_ls_ip.  Trace messages go to the trace file set up in the
	   previous example.  This example also uses the abbreviated
	   options.  Tracing for X.25 requires a -card option to indicate



 Hewlett-Packard Company	    - 9 -   HP-UX Release 11i: November 2000






 nettl(1M)							   nettl(1M)




	   which X.25 card to trace.

		nettl -tn pduout -e X25L2 ns_ls_ip -c x25_0

      6.   Determine status of tracing from the previous two examples.

		nettl -status trace

	   The output should resemble the following:

		Tracing Information:
		Trace Filename:			/var/adm/trace.TRC*
		Trace file size(Kbytes): 1000
		User's ID:		 0	Buffer Size:		32768
		Messages Dropped:	 0	Messages Queued:	0

		Subsystem Name:	     Trace Mask:		   Card:
		TRANSPORT	     0x30000000
		SESSION		     0x30000000
		NS_LS_IP	     0x10000000
		X25L2		     0x10000000			   x25_0

      7.   Stop tracing for all subsystems.

		nettl -traceoff -e all

      8.   Enable pduin and pduout tracing for ns_ls_driver (LAN driver)
	   subsystem.  Binary trace data goes to file /var/adm/LAN.TRC0.

	   The -file option of this command is only valid the first time
	   tracing is called.  The trace file is not automatically reset
	   with the -file option.  To change the trace output file, stop
	   tracing and start up again.	This example assumes that the
	   -traceon option is being used for the first time.

		nettl -tn pduin pduout -e ns_ls_driver -file /var/adm/LAN

      9.   Terminate the tracing and logging facility.

		nettl -stop

	   (See note for the -start option.)

 WARNINGS
      Although the nettl command allows the specification of all log classes
      and all trace kinds for all subsystems, many subsystems do not support
      all log classes and all trace kinds.  No error or warning will be
      issued if a subsystem does not support a log class or trace kind.
      Refer to the product documentation of the subsystem for information on
      supported log classes and trace kinds.




 Hewlett-Packard Company	   - 10 -   HP-UX Release 11i: November 2000






 nettl(1M)							   nettl(1M)




      Tracing to a file that resides on a NFS file system can impact system
      performance and result in loss of trace data.  It is recommended that
      NFS file systems not be used to contain tracing output files.

      Tracing to a file may not be able to keep up with a busy system,
      especially when extensive tracing information is being gathered.	If
      some data loss is encountered, the trace buffer size can be increased.
      Be selective about the number of subsystems being traced, as well as
      the kinds of trace data being captured.

      The nettl and netfmt commands read the /etc/nettlgen.conf file each
      time they are run (see nettl(1M) and netfmt(1M)).	 If the file becomes
      corrupted, these commands will no longer be operational.

 FILES
      /dev/netlog			 Kernel log pseudo-device file.

      /dev/nettrace			 Kernel trace pseudo-device file.

      /etc/nettlgen.conf		 Tracing and logging subsystem
					 configuration file.

      /etc/rc.config.d/nettl		 Contains variables which control
					 the behavior of nettl during system
					 startup.

      /var/adm/conslog.opts		 Default console logging options
					 filter file as specified in
					 /etc/nettlgen.conf.

      /var/adm/nettl.LOG00		 Default log file as specified in
					 /etc/nettlgen.conf.

 AUTHOR
      nettl was developed by HP.

 SEE ALSO
      netfmt(1M), nettlconf(1M), nettlgen.conf(4).
















 Hewlett-Packard Company	   - 11 -   HP-UX Release 11i: November 2000