remote_open()

Open a communication session with a remote PATROL Agent.

Syntax

remote_open(host,port,[account-mode],[username],[password],
[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*

  • "" or omitted--ignore username and password and use the following inherited account information:
    • nearest instance
    • parent of the nearest instance
    • application to which the nearest instance belongs
  • "NONE" -- password argument supplies an unencrypted password for username
  • "PEM" --password argument supplies a PEM-encrypted password for username
  • "DES" --password argument supplies a DES-encrypted password for username

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:

  • protocol -- only TCP is currently supported. TCP is the default when this option is not specified.
  • heartbeat --the number of seconds between attempts to keep the connection open. Default value is 300.
  • scope -- sharedprocess or none. Specifies a scope for the connection to determine whether the connection is implicity closed when remote_close() was not explicitly called. See Scope Option

IPPreference

defines the IP type comunication preference. The following values are legal:

  • IPv4 -- IPv4 only
  • IPv6 -- IPv6 only
  • IPv4,IPv6 --Preference for IPv4 , if none exists then IPv6 (default)
  • IPv6,IPv4 -- Preference for IPv6, if none exists then IPv4

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 
Unable to open remote session to agent (for reason other than authentication error or reaching maximum number of outbound session)

144

M_PSL_REMOTE_OPEN_AUTHENTICATION_ERR 
Unable to open remote session because account credentials failed to authenticate session

146

E_PSL_MAX_REMOTE_SESSION_REACHED 
The Agent has reached the maximum number of simultaneous remote connections specified by the Agent configuration variable: /AgentSetup/maxOutboundRemoteSessions
No connection will be attempted.

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:

targetHost="<myhost>";
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:

Event Class: RemProcess
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");
Was this page helpful? Yes No Submitting... Thank you

Comments