Defining Agent actions by creating a settings file (lockdown.conf)

Agent actions can be prescribed by creating a settings file (lockdown.conf) on Agent as follows:

  • Make the settings value that appears on the Agent Operation Settings screen static

  • Restrict the range of directories to be monitored

  • Specify the modules to be executed for a job execution
  • Prohibit an update of the Agent modules

(1) File storage location of the settings file (lockdown.conf)

Create the lockdown.conf file in the install directory of Agent.

The default installation directory of Agent is as follows:

in Windows
C:\HULFT Family\hulftiot
in Linux
/opt/hulftiot
Note

When you modify the existing lockdown.conf file, we recommend backing up the file before making any changes.

(2) Enabling changes of the settings file (lockdown.conf)

When you create the lockdown.conf file or modify the settings of the lockdown.conf file, you can enable the lockdown.conf file by the following procedures:

1. On the IoT equipment, create or edit the lockdown.conf file.

2. On the IoT equipment, stop Agent.

3. On the IoT equipment, restart Agent.

The lockdown.conf file is now enabled.

Note

When you modified the value described in the lockdown.conf file, restarting Agent makes the values enabled.

However, if you want to disable the setting that is once enabled, you must disable the lockdown.conf file. If you delete the line of the setting or delete the value in the lockdown.conf file, the setting is not disabled. For details about disabling the settings file, see (3) Disabling the settings file (lockdown.conf).

(3) Disabling the settings file (lockdown.conf)

You can disable the lockdown.conf file by the following procedures:

1. On the IoT equipment, stop Agent.

2. On the IoT equipment, delete the lockdown.conf file.

3. Delete the instance of Agent in which you want to disable the lockdown.conf file by using the Agent List screen of Manager.

4. On the IoT equipment, delete the line of "agent_id" in the agent.conf file.

5. On the IoT equipment, restart Agent.

The lockdown.conf file is now disabled.

(4) Making the settings value on the Agent Operation Settings screen static

You can configure the Agent operation not only by the Agent Operation Settings screen of Manager but also by creating the settings file (lockdown.conf) on Agent. However, you cannot change the values that are prescribed by creating the settings file (lockdown.conf) from the screen of Manager.

  • Only the items that you want to make them static must be written in the lockdown.conf file.

    For the items that are not written in the lockdown.conf file, you can change the values by using the Agent Operation Settings screen of Manager.

  • For the items that are written in the lockdown.conf file, you can see the values on the screen of Manager, but you cannot change them by using the screen.

  • The contents of the lockdown.conf file are enabled when Agent starts next time.

  • If the value that is not able to be specified as a settings value or the path that does not exist has been specified in the lockdown.conf file, Agent fails to start.

  • If the item name that is described in the lockdown.conf file is incorrect, Agent ignores the item.

Description format of the lockdown.conf file
Parameter-name-in-the-following-table = [Value]

Table 6.1 Items to make the value that is displayed on the Agent Operation Settings screen static
Item Parameters Field name in the Agent Operation Settings screen Description Specifiable values Unit
Agent - Manager Communications polling_interval Polling Interval Specify the interval at which Agent polls Manager. 1 to 5097600

Seconds

*1
rcvque_polling_interval Receive Queue Polling Interval Specify the interval at which Agent polls the Receive Task Queue. 1 to 5097600

Seconds

*1
communication_time_limit_enabled Communication Time Limit

Specify whether the time period when Agent communicates with Manager is restricted.

If you restrict the time period for Agent to communicate with Manager, specify Start Time and End Time, too.

0: Do not restrict the communication hours

1: Restrict the communication hours

 -
start_communication_time Start Time

Specify the time of day when Agent can start to communicate with Manager if you limit the time when Agent can communicate with Manager.

Specify the value with "End Time".

When you specify only this value or the same value as "End Time", Agent fails to start.

 0 to 23 o'clock
end_communication_time End Time

Specify the time of day when Agent ends the communication with Manager if you limit the time when Agent can communicate with Manager.

Specify the value with "Start Time".

When you specify only this value or the same value as "Start Time", Agent fails to start.

 0 to 23 o'clock
Connecting connection_retry_count Connection Retry Count Specify the number of times to retry a connection when Agent fails to connect to HULFT. 0 to 9999 Times
connection_retry_interval Connection Retry Interval Specify the amount of time to wait before Agent retries a connection when Agent fails to connect to HULFT. 0 to 9999 Seconds
socket_timeout Socket Read Timeout

Specify the time until a timeout of Agent occurs when Agent does not receive a response from HULFT during a socket communication between Agent and HULFT.

If a timeout occurs, Agent regards the state as a communication error and disconnects the communication.

 10 to 259200 Seconds
request_timeout Request Timeout

Specify the time until a timeout of Agent occurs when Agent does not receive a response from Manager during any communications between Agent and Manager.

If a timeout occurs, Agent regards the state as a communication error and disconnects the communication.

 10 to 259200 Seconds
socket_buffer_size Socket Buffer Size

Specify the socket buffer size that is applied to socket communication from Agent to HULFT.

If 0 is specified, the system value is used.

 0, 4096 to 2147483647 Bytes
Resending auto_retry_count Auto Resend Retry Count Specify the number of times that Agent retries a transfer when a communication error causes a failure during a file transfer to HULFT. 0 to 255 Times
auto_retry_interval Auto Resend Retry Interval Specify the amount of time to wait before Agent retries a transfer when a communication error causes a failure during a file transfer to HULFT. 0 to 9999 Seconds
send_multiplex_level Send Process Multiplex Level

Specify the maximum number of send processes (huliotsend) that Agent can start at the same time.

If the number of transfer files in an instance of Agent exceeds the maximum number of send processes, Agent delays transferring the extra files until the next trigger fire after the time of the monitoring interval that is specified on the Transfer Settings screen elaplsed.

 1 to 99 Processes
Receiving *2 Size of Receive Task Queue

Specify the maximum number of Receive Tasks that can be registered in the Receive Task Queue for the file distribution function.

If the number of tasks exceeds the maximum, the new task will not be added to the queue.

 1 to 9999 Tasks
Jobs job_timeout Job Timeout

Specify the amount of time to wait before generating an error when the result of a job for a file transfer or file distribution is not returned.

If 0 is specified, Agent keeps waiting for a result without timing out.

 0, 10 to 86400 Seconds
Logs log_output_mode Log Output Mode

Specify whether to have Agent always output Send Logs or whether to have Agent output Send Logs only when an error occurs.

If 0 is specified, logs are output only when an error occurred.

If 1 is specified, logs are always output.

 0 or 1 -
send_log_pool_size Send Log Pool Size

Specify the size of Send Logs that are kept in Agent.

 1048576 to 1073741824 Bytes *3
trace_log_pool_size Trace Log Pool Size

Specify the size of Trace Logs that are kept in Agent

 1048576 to 1073741824 Bytes *3

*1

:

Specify Polling Interval and Receive Queue Polling Interval as follows:
Interval that you can set

Specifiable values

(in seconds)

 Description

1 second to 59 seconds (in seconds)

 1 to 59 Specify from 1 to 59.

1 minute to 59 minutes (in minutes)

 60 to 3540

Specify a multiple of 60.

Example) 3 minutes: 180, 15 minutes: 900

1 hour to 23 hours (in hours)

 3600 to 82800

Specify a multiple of 3600.

Example) 3 hours: 10800, 15 hours: 54000

1 day to 59 days (in days)

 86400 to 5097600

Specify a multiple of 86400.

Example) 3 days: 259200, 15 days: 1296000

*2

:

Size of Receive Task Queue cannot be fixed-value.

*3

:

Specify Send Log Pool Size and Trace Log Pool Size as follows:
Size that you can set

Specifiable values

(in bytes)

 Description

1 MB to 1024 MB (in megabytes)

 1048576 to 1073741824

Specify a multiple of 1048576.

Example) 100 MB: 104857600, 500 MB: 524288000
Example description for the lockdown.conf file
The following example shows a lockdown.conf file when you fix Polling Interval to 1 minute and Receive Queue Polling Interval to 1 hour.
polling_interval = 60
rcvque_polling_interval = 3600

(5) Restricting the range of directories to be monitored

You can restrict the range of directories to which the monitored files are stored to the specified directory and its descendent directories.

If the /usr/AAA/ directory is specified as the directory for monitored files, Agent can monitor the following files.

Files that can be monitored:

/usr/AAA/a.txt

/usr/AAA/AAA/a.txt

/usr/AAA/BBB/a.txt

Files that cannot be monitored:

/usr/a.txt

/etc/a.txt

/usr/BBB/a.txt

Figure 6.1 Area accessible by Agent

Description format of the lockdown.conf file
permission_filepath_list = [Name-of-the-file-in-which-the-paths-that-Agent-can-monitor-are-written]
permission_filepath_list

Specify the absolute path (combination of the directory name and file name) of the file in which the paths that Agent can monitor are listed, not the path itself that Agent can monitor.

In the specified file, write down the directories that you allow Agent to access with absolute paths separated by a newline code.

You cannot write a relative path in the file. If a transfer file or a halfway part of the path is a symbolic link, write down both the absolute path of the symbolic link and the absolute path of the real file.

Example description for the lockdown.conf file
This is an example of the lockdown.conf file that /opt/hulftiot/.whitelist is specified for the file in which the paths that Agent can access are written.
permission_filepath_list = /opt/hulftiot/.whitelist
Note

If the lockdown.conf file contains nothing or only comments, Agent does not start.

(6) Specifying files to exclude

You can specify files to exclude from the following monitoring targets:

  • Monitoring target of Agent

  • Destination where files are distributed to

Even when system files or hidden files are included in the targets specified with "Monitored File Name" or "File Name at Send Destination" on the operation screen of Manager, the files are not transferred or distributed if you specify exclusion of those files from the monitoring targets.

Description format of the lockdown.conf file
ignore_file_list = ［Filepath-to-the-list-of-files-to-exclude-from-the-monitoring-target-of-Agent-and-file-distribution］
ignore_file_list

Specify the absolute path (combination of the directory name and file name) of the file in which the names of files to exclude are listed, not the path to a file to exclude from the monitoring target of Agent and file distribution.

Example description for the lockdown.conf file
This is an example of the lockdown.conf file, when /opt/hulftiot/.ignore is specified for the file where the names of the files to exclude from the monitoring target of Agent and file distribution are written.
ignore_file_list = /opt/hulftiot/.ignore
Example description for the .ignore file

Specify "whether to use regular expression in pattern description" and "file name pattern to exclude from monitoring target of Agent or file distribution" delimited by a comma (,).

If you register two or more exclusion patterns, separate them with a newline code.

If the line top is a number sign (#), the line is to be seemed as a comment line.

Note

If multi-byte characters are included in the name of the file to exclude, use the characters supported by the operating system locale.

# When you specify only a file name: "file-a.txt" in any directory is excluded
false, file-a.txt

# When you specify a full-path: "file-b.txt" in the specified path is excluded
false, /home/guest/work/file-b.txt

# Specification using a wild card
false, /home/guest/work1/*
false, /home/guest/work2/*.txt

# Exclusion using a regular expression (from file-1.txt to file-9.txt)
true, file-[1-9].txt
Note

  • If the lockdown.conf file contains nothing or only comments, Agent does not start.

  • If the .ignore file contains nothing or only comments, Agent does not start.

(7) Specify a module to be executed for a job execution

You can specify a module that the following jobs execute.

  • Pre-send Job for file transfer

  • Successful Job for file transfer

  • Unsuccessful Job for file transfer

  • Successful Job for file distribution

Description format of the lockdown.conf file
job_exec_module = [module-to-be-executed]
job_exec_module

Specify the module to be executed by an absolute path.

When you specify this option, you must choose [Step Execution] for the following items on the Transfer Settings screen and Receive Settings screen. You cannot choose [Script Execution].

  • Pre-send Job Execution Mode

  • Successful Job Execution Mode

  • Unsuccessful Job Execution Mode

  • Job Execution Mode

When you specify this option, the characters that are input for the following items on the Transfer Settings screen and Receive Settings screen become the characters that are passed to the module to be executed as a parameter.

  • Pre-send Job on the file transfer screen

  • Successful Job on the file transfer screen

  • Unsuccessful Job on the file transfer screen

  • Job on the Reception Settings screen

When you failed to execute the module, the contents of the module appears in the logs. At this time, the name of the executed module does not appear.

Example description for the lockdown.conf file
The following example is the lockdown.conf file when you specify /bin/busybox for the module to be executed.
job_exec_module = /bin/busybox

Figure 6.2 Flow of the job execution when you specify the module to be executed

1. Specify the module to be executed in the lockdown.conf file.

2. Specify the parameters on the Transfer Settings screen and Receive Settings screen.

3. Agent executes the module with the parameters that are sent by Manager.

(8) Prohibit an update of the Agent modules

You can update the modules from Manager. You can prohibit Manager from updating the Agent modules by setting the lockdown.conf file.

Description format of the lockdown.conf file
lockdown_remoteupdate = [Value]
lockdown_remoteupdate

If you prohibit Manager from updating the Agent modules, specify 1.

If you specify 1 for this option, the Agent module update from Manager fails.

Example description for the lockdown.conf file
The following example is the lockdown.conf file when you prohibit Manager from updating the Agent modules.
lockdown_remoteupdate = 1