jcfallogstart

Function

Starts a remote monitoring log file trap.

Executing this command collects log files on a monitored host, and sets a line in a log file that matches the conditions in the action definition file of the remote monitoring log file trap as a JP1 event. The event is then registered on an event server.

Specifying the -f option adds a new profile for a remote monitoring log file trap, and then starts a process. If a profile with the same monitoring name already exists on the specified monitored host when the profile has stopped, the trap's action definition file is overwritten, and a remote monitoring log file trap process is started. If the profile is running, the action definition file is overwritten and saved on the server, and an error message is displayed before the process stops. At this point, the profile is running with the operation definition that existed before the action definition was overwritten. If the -f option is not specified, the profile process for an existing remote monitoring log file trap is started.

Log files in different data formats cannot be processed together. For such cases, start a separate remote monitoring log file trap for each format.

Note that a maximum of five commands can be executed concurrently.

The following conditions must be satisfied to execute this command:

• The IM Configuration Management service is running

• There is a remotely monitored host in the remote monitoring configuration.

• A remotely monitored host has already collected host information.

• For SSH communication, SSH authentication can be performed by using the applicable remotely monitored host and public key encryption.

• For NetBIOS (NetBIOS over TCP/IP) communication, the log file to be monitored is shared.

To Page Top

Format

jcfallogstart
        -a monitoring-name
        -o monitored-host-name
        [-h logical-host-name]
        [-f remote-monitoring-log-file-trap-action-definition-file-name
          -c character-encoding
          [-filter filter]
          [-m maximum-length-of-data-treated-as-event (bytes)]
          [-p log-data-output-source-program-name]
          [-r]
          [-t file-monitoring-interval (seconds)]
          log-file-name1[ ...log-file-name32]]

To Page Top

Execution permission

In Windows: Administrator permissions

In UNIX: Superuser permissions

To Page Top

Storage directory

In Windows:

Manager-path\bin\imcf\

In UNIX:

/opt/jp1imm/bin/imcf/

To Page Top

Arguments

-a monitoring-name

Specifies the monitoring name used to identify the remote monitoring log file trap.

Specify a character string with a maximum of 30 bytes for the monitoring name. Alphanumeric characters, hyphens (-), and underlines can be used. The first character must be an alphanumeric character. The monitoring name is not case sensitive.

A paired monitoring name and a monitored host must be unique, and cannot be the same as another pair specified by jcfallogstart. Note, however, that the same monitoring name as the one specified by jevlogstart of JP1/Base can be used.

-o monitored-host-name

Specifies the name of the monitored host for a remote monitoring log file trap you want to start.

-h logical-host-name

Specifies the name of the logical host on which you want to execute the command. If this option is omitted, the logical host name specified for the JP1_HOSTNAME environment variable is set. If no logical host name is set for JP1_HOSTNAME, the physical host name is set.

-f remote-monitoring-log-file-trap-action-definition-file-name

Specifies the name of the action definition file as a full path or a relative path from the current directory with a maximum of 256 bytes. When specifying a relative path, do so in such a way that the full-path name with the directory name will be no more than 256 bytes.

The action definition file can be placed in any directory, and any file name can be specified.

Specifying this option creates a new remote monitoring log file trap and starts it. If this option is omitted, an existing remote monitoring log file trap is started.

-c character-encoding

Specifies the character encoding of a log file. This option can be specified only when the -f option is specified.

The following character encodings can be specified.

Table 1‒9: Character codes

OS	Japanese	English	Chinese
AIX	SJIS When SJIS is specified, SJIS/Ja_JP is set. SJIS/Ja_JP SJIS/Ja_JP.IBM-932 EUC When EUC is specified, EUC/ja_JP is set. EUC/ja_JP EUC/ja_JP.IBM-eucJP UTF-8 When UTF-8 is specified, UTF-8/JA_JP is set. UTF-8/JA_JP UTF-8/JA_JP.UTF-8 C	C	GB18030 When GB18030 is specified, GB18030/Zh_CN.GB18030 is set. GB18030/Zh_CN.GB18030 GB18030/Zh_CN UTF-8 When UTF-8 is specified, UTF-8/ZH_CN is set. UTF-8/ZH_CN UTF-8/ZH_CN.UTF-8 C
HP-UX	SJIS When SJIS is specified, SJIS/ja_JP.SJIS is set. SJIS/ja_JP.SJIS SJIS/japanese EUC When EUC is specified, EUC/ja_JP.eucJP is set. EUC/ja_JP.eucJP EUC/japanese.euc UTF-8 When UTF-8 is specified, UTF-8/ja_JP.utf8 is set. UTF-8/ja_JP.utf8 C	C	GB18030 When GB18030 is specified, GB18030/zh_CN.gb18030 is set. GB18030/zh_CN.gb18030 UTF-8 When UTF-8 is specified, UTF-8/zh_CN.utf8 is set. UTF-8/zh_CN.utf8 C
Linux	SJIS/ja_JP.sjis#1 SJIS/ja_JP.SJIS#1 UTF-8 When UTF-8 is specified, UTF-8/ja_JP.UTF-8 is set. UTF-8/ja_JP.UTF-8 UTF-8/ja_JP.utf8 C	C	GB18030 When GB18030 is specified, GB18030/zh_CN.gb18030 is set. GB18030/zh_CN.gb18030 UTF-8 When UTF-8 is specified, UTF-8/zh_CN.utf8 is set. UTF-8/zh_CN.utf8 C
Solaris	EUC When EUC is specified, EUC/ja is set. EUC/ja EUC/japanese EUC/ja_JP.eucJP SJIS When SJIS is specified, SJIS/ja_JP.PCK is set. SJIS/ja_JP.PCK UTF-8 When UTF-8 is specified, UTF-8/ja_JP.UTF-8 is set. UTF-8/ja_JP.UTF-8 C	C	GB18030 When GB18030 is specified, GB18030/zh_CN.GB18030 is set. GB18030/zh_CN.GB18030 GB18030/zh_CN.GB18030@pinyin GB18030/zh_CN.GB18030@radical GB18030/zh_CN.GB18030@stroke UTF-8 When UTF-8 is specified, UTF-8/zh.UTF-8 is set. UTF-8/zh.UTF-8 UTF-8/zh_CN.UTF-8 UTF-8/zh_CN.UTF-8@pinyin UTF-8/zh_CN.UTF-8@radical UTF-8/zh_CN.UTF-8@stroke C
Windows	SJIS	SJIS#2 C	GB18030

#1

Valid only when the monitored OS is SUSE Linux.

#2

If the product runs on an English OS, the character encoding is C even if you specify SJIS for the character encoding.

-filter filter

Specifies a filter, when filters have already been set, that uses regular expressions to filter log files obtained on a remotely monitored host.

When this option is specified, only log data that matches the specified regular expressions is transferred to the manager. Specify this option to control the amount of log file data that is transferred from a remotely monitored host to the manager.

This option can be specified only when the -f option is specified.

This option is valid only when the OS on the remotely monitored host is UNIX. As a prerequisite condition, the grep command must be able to be executed over an SSH connection. When the OS on the remotely monitored host is Windows and this option is specified, it is ignored.

The regular expression formats that can be specified are the same as the formats of the extended regular expressions that can be specified in the -E option for the grep command on the remotely monitored host. No environment variables can be used.

Specify a character string with a maximum of 128 bytes for regular expressions. Characters that can be specified in the string are ', ", <, >, alphanumeric characters (excluding control characters), spaces, and symbols. If the character string contains a space, the entire string must be enclosed in double-quotation marks (").

Path examples for the grep command are given below. For details, see the documentation about the grep command in the applicable OS.

• For Linux: /bin/grep

• For Solaris: /usr/xpg4/bin/grep

• For an OS other than Linux and Solaris: /usr/bin/grep

-m maximum-length-of-data-treated-as-event (bytes)

Specifies the number of bytes to be read from the beginning of a line in a log file. From 1 to 1,024 bytes can be specified. If this option is omitted, 512 is set.

The last character in the line is converted to the \0 symbol and indicates the end of the line. If a line in a log file exceeds the number of bytes specified for this option, the last byte is converted to \0.

The value specified for this option indicates the valid length of a line in the entered log file. Therefore, ensure that the regular expressions in the MARKSTR parameter in the action definition file of a remote monitoring log file trap and the regular expressions in the ACTDEF parameter are within the length specified here. In short, if there are any regular expressions corresponding to a column that exceed the valid length, they are not checked.

-p log-data-output-source-program-name

Specifies the name of the program to which log data is output. The specified name is displayed in the Event Console window of JP1/IM - View.

The following names are displayed.

In Windows:

/HITACHI/JP1/NT_LOGTRAP/log-data-output-source-program-name

In UNIX:

/HITACHI/JP1/UX_LOGTRAP/log-data-output-source-program-name

If this option is omitted, /HITACHI/JP1/NT_LOGTRAP is displayed for Windows and /HITACHI/JP1/UX_LOGTRAP is displayed for UNIX.

-r

If this option is omitted and any of the following cases apply, the system tries to collect data at the interval specified in the -t option until the log data can be collected.

• The remotely monitored host cannot be accessed when the remote monitoring log file trap is started

• The remotely monitored host cannot be accessed while the remote monitoring log file trap is running

• The log file that is to be monitored cannot be accessed when the remote monitoring log file trap is started

• The log file that is to be monitored cannot be accessed while the remote monitoring log file trap is running

Specify the -r option for the following cases:

• The remotely monitored host can be accessed after the remote monitoring log file trap starts.

• The log file that is to be monitored is created after a remote monitoring log file trap starts.

• You want to continue monitoring a remotely monitored host even if you cannot access it.

If this option is omitted, one or the other of the following occurs:

• If the log file that is to be monitored cannot be obtained when the remote monitoring log file trap starts, the startup process stops and processing terminates.

• If the log file that is to be monitored cannot be collected while it is running, retry is attempted for the number of times specified in the action definition file for the log file trap at the interval specified in the file.

-t file-monitoring-interval (seconds)

Specifies the file monitoring interval. A value from 60 to 86,400 (seconds) can be specified. If you omit this option, 300 is set.

When a log file in WRAP2 format is monitored

If wrap-around is performed frequently or a long monitoring interval is specified, the remote monitoring log file trap is overwritten before it reads data, causing some data to be lost. To prevent unread data, use the following formula for the monitoring interval:

log-file-size (bytes) × number-of-log-files > output-size-per-second (bytes) × monitoring-interval (seconds)

log-file-name1 [...log-file-name32]

Specifies the names of the log files to be monitored. Specify a character string with a maximum of 256 bytes for the log file name. If the monitored host OS is Windows, use the network path name without the host name for specification. If the OS is UNIX, use the full-path name. Note that wildcard characters cannot be specified for the log file to be monitored.

For a monitored host running UNIX, only log files with file paths consisting of alphanumeric characters, hyphens (-), underscores (_), periods (.), and slashes (/) can be monitored. File paths that include any other characters might not be monitored correctly.

A maximum of 32 files, and the following file formats, can be specified:

• Sequential file (SEQ)

• Sequential file (SEQ2)

• Wrap around file (WRAP2)

To Page Top

Return values

0	Trap started successfully
4	Invalid argument
6	Unable to connect to the server
7	Invalid host information
8	The specified monitoring name is already running
9	Profile threshold value exceeded
10	Error in obtaining exclusive edit rights
11	Invalid action definition file
12	Invalid authentication definition file
13	Communication error
14	Invalid DB
17	Invalid permissions
18	Input/output error
21	Upper limit for number of concurrent executions reached
255	Internal error
Other values	Other error

To Page Top

Example 1

Start the remote monitoring log file trap monitoringName on host1:

jcfallogstart -a monitoringName -o host1

To Page Top

Example 2

Create a new action definition file for a remote monitoring log file trap and start it:

jcfallogstart -a monitoringName -o host2 -f actionDefinition.conf -c SJIS -filter ".*-E" /log/sample.log

To Page Top