remote_open()
Open a communication session with a remote PATROL Agent.
Syntax
[options],[IPPreference])
Parameter
Parameter | Definition |
|---|---|
host | host name on which the remote PATROL Agent is running |
port | TCP/IP port number on which the remote PATROL Agent is listening |
account-mode | optional account information that is used to open the session with the remote PATROL Agent*Valid Values*
|
Note: For more information about encryption, see the PATROL Security User Guide. |
username | username that is required to open a session with the remote PATROL Agent. If username is not supplied, the remote session will be opened with inherited account information as for account-mode "". |
password | password that is required to open a session with the remote PATROL Agent. If password is not supplied, the remote session will be opened with inherited account information as for account-mode "". password must be unencrypted, PEM-encrypted, or DES-encrypted as specified by account-mode |
options | comma delimited list of options name/value pairs in the format below: option_name=value Options:
|
IPPreference | defines the IP type comunication preference. The following values are legal:
|
Description
The remote_open() function opens a communication session between the PATROL Agent on which it is running and the PATROL Agent identified by host and port, using user account credentials according to specified the account-mode. The account credentials must be valid on the remote PATROL Agent.
If the IPPreference optional parameter is not used, the default IPPreference is IPv4, IPv6.
When remote_open() succeeds, it returns a session ID. When the remote_open() fails, it returns the null string "" and sets the PSL errno variable.
errno Value | Failure Description |
|---|---|
109 | E_PSL_REMOTE_OPEN_ERR |
144 | M_PSL_REMOTE_OPEN_AUTHENTICATION_ERR |
146 | E_PSL_MAX_REMOTE_SESSION_REACHED |
Scope Option
The scope option determines the behavior with respect to closing the remote session. When the remote_open() is called, the scope option can be specified as one of the following:
- "scope=shared" --the session will remain open after the PSL process exits so other PSL processes in the KM may use it. This option is conceptually similar to a shared channel.
- "scope=process" --the agent will close the session after the PSL process exits if it was not already closed by an explicit called to remote_close().
- "scope=none" --backward compatible behavior, and the default if no scope option is specified. The agent will display a warning in the agent's error file if a process exits without explicitly closing the connection withremote_close(). The agent displays the warning a maximum of 10 times.
The number of remote session that the Agent can open is limited by the agent configuration variable/AgentSetup/maxOutboundRemoteSessions (default maximum 256).
The remote_open() function returns the session ID if successful; otherwise, it returns the NULL string.
Using the Remote Functions
The remote file functions consist of the following PSL built-in functions:
- remote_open()
- remote_check()
- remote_file_send()
- remote_event_query()
- remote_event_trigger()
- remote_close()
To effectively use these functions, it is important to understand how these functions work together.
Understanding Remote Functions
The remote_open() function connects to a remote agent, supplies authentication information, and returns. Ifremote_open() returned successfully, the session was opened, but its ongoing validity is not guaranteed. To verify that a remote session is still valid, the remote_check() function can be used.
The remote_file_send() function transfers an ASCII file to a remote PATROL Agent. However, the function only starts the operation and returns immediately. The actual file transfer takes place in the background. The remote_file_send()function does not verify that the file transfer was successful. Therefore, you must ensure that the file transfer has been completed prior to using the remote_close() function to close the session with the remote agent, or before the PSL process is allowed to terminate if scope=process was specified.
When the file transfer is complete, an event is generated on the remote agent indicating that the file has been transferred. If the remote_file_send() catalog and class parameters are not supplied, an event with the following characteristics will be generated on the remote target host:
Event Class = RemProcess
Origin = PEM/DS,
Description = File <output_file_name>, Operation (A), Stream Id <sendId>
However, by supplying an event catalog and event class to the remote_file_send() function, you can define the event that gets generated. You could ensure that the file transfer is complete by waiting for this event to be generated on the remote PATROL Agent using the remote_event_query() function.
Example
The following example sends a file to a remote agent and creates two events on the remote agent if the transfer is successful:
targetPort="<myport>";
user="<myuser>";
password="<mypassword>";
myencrypted_passwd = encrypt(password, "PEM");
source_file = "<full path to myfile>";
remote_file = "<myfile>";
print("Start remote_file_send example at ".asctime(time(),"%H:%M:%S %m-%d-%Y")."\n");
printf("TargetHost <%s> on Port <%s>\n", targetHost, targetPort);
printf("User <%s> Password <%s>\n", user, password);
# Open session to remote Agent
print("Open the channel.\n");
sess=remote_open(targetHost, targetPort, "PEM", user, myencrypted_passwd);
print("errno=".errno."\n");
printf("Session #<%s> \n", sess);
#print("Sleep 5 seconds.\n");
#sleep(5);
print("Send the file.\n");
if (sess=="") {
error = "Error opening session to the Patrol Agent on the target Machine\n".
"Please make sure the values are correct for:\n".
" Target Host: " . targetHost."\n".
" Target Port: " . targetPort."\n".
" Username: ". user."\n".
" Password: ". password."\n";
print(error);
}
else {
#+++
# We have a session so try and send the file to remote agent
# Specify the absolute path for the dest. file
# Set the permissions to -rw-rw-rw- 666 Octal = 438 Decimal
#---
if
(remote_file_send(sess,source_file,remote_file,"STD","RemProcess","<myid>","438")!=1)
{
# remote_file_send failed. Print error message\n".
error = "Error sending file to the Patrol Agent on the target Machine\n".
"Please make sure the values are correct for:\n".
" Target Machine: " . targetHost."\n".
" Target Port: " . targetPort."\n";
print(error);
}
else
{
#+++
# Wait for the file to transfer by searching for its logged event
# This will wait for 30 seconds for the transfer to complete then
# it gives up.
#---
wait_loops = 15;
while (wait_loops > 0)
{
sleep(2);
cmd_data = remote_event_query(
sess, # Session ID
"1", # return a maximum of 1 event
"1", # time out in one minute
"\n", # separate events with newline
"Event ID <%{EV_ID}>", # return event id triggered
"", # any start time
"", # any end time
"O", # only OPEN status
"", # only INFORMATION type
"", # any node
"PEM/DS", # origin
remote_file, # file name in description
"", # any ID range
"RemProcess", # RemProcess event class
"" # any severity
);
if (cmd_data != "")
{
wait_loops = 0;
}
else
{
wait_loops--;
}
}
if (cmd_data == "")
{
error= "Error: remote_event_query was unable to verify".
"remote_file_send()\n".
"Please check the Event Manager on target:\n".
" Target Machine: " . targetHost."\n".
" Target Port: " . targetPort."\n";
print(error);
}
else
{
print("remote_file_send verified by remote_event_query: ".cmd_data);
}
}
#+++
# Close up the session with the remote agent
#---
remote_close(sess);
}
The previous example creates the following events on the remote agent if the transfer is successful:
Type: INFORMATION
Origin: PEM/DS
Description: File <myfile>, Operation (W), Stream Id <myid>
Event Class: Disconnect
Type: INFORMATION
Origin: <Source hostname>
Description: Console console_id disconnected.
The following example uses several remote functions to access a remote PATROL Agent.
# Description: Remote PSL execution.
#
# You need to run two agents for this example:
# From (localhost, port 1234) you want to execute a remote PSL script
# on (remotehost, port 5678).
#
# The PSL script (see your_psl_cmd below) is any PSL statement which returns a string.
# It will be executed on (remotehost, port 5678) using PATROL console
#--------------------------------------------------------------
#
# The remote agent where the PSL script is to be executed
remote_host = "remotehost"; # replace with remote host name
remote_port = "5678"; # replace with remote Agent port
your_username = "username"; # Your account details
max_time_to_wait = "1"; # maximum time (in minute) the PSL process will block
your_id = "my_id"; # A local id selected to uniquely identify they query
# PSL script to be executed by <remote_host>
# It should return a string.
# Increase <max_time_to_wait> if this script will take a lot of time
#
your_psl_cmd= "get_vars(\"/\");";
#
# 0. Use an already encrypted password if you don't want to store
# the password in the KM. It is recommended that:
#
# - you encrypt your real password using encrypt()
# - you store the encrypted password in a file or in the KM
# use "pem" encryption it is safer than "des":
# "pem" encryption is "des" encryption combined with an internal
# encryption. Storing the result of a "pem" encryption is safe
# since it cannot be used to log to any Unix (or other) systems.
#
your_pwd = "becool";
your_encrypted_pwd = encrypt(your_pwd,"pem");
#
# 1. Open the remote connection with agent (nanou,5678);
#
sess=remote_open(
remote_host,
remote_port,
"pem",
your_username,
your_encrypted_pwd
);
print("Session number result of remote_open:".sess."\n");
print("Sending command: " . your_psl_cmd . "\n");
#
# Dispatch the remote PSL.
#
trigger_res = remote_event_trigger(
sess,
remote_host, # Name of remote host
"STANDARD", # Name of event catalog
"RemPsl", # Name of event class in StdEvents.ctg
"INFORMATION","5", # Type and severity
your_psl_cmd, # First argument to <ev_exec_name>
your_id # Second argument to <ev_exec_name>
# This local id will uniquely identify
# the result of the PSL exec.
);
print("Result of trigger->".trigger_res."\n");
query_res=remote_event_query(
sess,
"1", # Finish query when 1 event is found
max_time_to_wait, # Time in min. PSL process will block
"", # N/A (event separator)
"%{EV_ARG1}\n", # Format to print result of query
"","", # Any start/end time
"", # Any Status
"", # Any Event Type
"", # any node
"", # any origin
your_id, # pattern in filter should be your local id
"", # match any eventid range in filter
"Result" # match only event from class 'Result'
);
print("Result of remote PSL execution on (" . remote_host . "," . remote_port .
"):\n" . query_res ."<------\n");
#
# Send the file to remote agent
# The remote agent will write the content of file "/tmp/MyFile" in
# "$PATROL_REMOTE/MyRemoteFile".
# Also standard event RemProcess will be sent to the remote
# agent carrying the three dynamic arguments:
# - /tmp/MyFile
# - Operation (reserved for future use)
# - MyFileId
# A notification command can be executed at the remote agent
# to complete the processing of the file sent
#
transfer_res = remote_file_send(
sess, # remote session handle
"/tmp/MyFile", # full source file name
"MyRemoteFile", # destination name in $PATROL_REMOTE
"STD","RemProcess", # Use standard event FileProcess
"MyFileId" # my id to identify this operation
);
print("Result of transfer->".transfer_res."\n");
close_res = remote_close(sess);
print("Result of close->".close_res."\n");