## SafeFire Links

### v1.3a

# Remote Control Operations

## Introduction

Remote control in SafeFire is done using PIPES. Term "remote" means that SafeFire process can be controlled from another SafeFire process. To control SafeFire process that is located at the another computer, you must either has network environment that has Remote Pipe ability (i.e. Lan Server/Peer/Netware LAN) or use SFCGI. In the SFCGI case SFCGI web server can be located at either computer running SafeFire or computer that can access pipes at SafeFire computer.

## Plugin Description

For remote control the new plugin library is introduced: PL_RCON:REMOTE_PIPE with the next configuration variables:

Name | Type | Default Value | Description
--- | --- | --- | ---
server | boolean | no | Will this instance act as server. For use of Remote control, one instance must be started as server. Other must be started as clients to connect to server. One server can handle multiple clients at the same time. Server instance must be started before any client instance.
syncstart | boolean | no | Have the connection be established in the "startup" phase. Usefull for scripting. By default connection will be established in background.
waittime | decimal | 1 | Used in case when client tries to access a server and the server doesn't have any free pipes avaiable. The option defines maximum time (in seconds) to wait before pipe will become available. To disable waiting set it to -1. Setting this option at server will change default time for clients to wait. For client to wait default time (set at server), use value 0.
sendbroadcast | boolean | no | Retransmit broadcast messages. But in any case timer messages are not retransmitted.
syncwait | decimal | 10 | How long to wait for responce to sync messages. This is used to signal deadlocks.
pipe | string | \PIPE\SAFEFIRE\RCON | Name of pipe to communicate. Must start with \PIPE\ for local or with \\SERVER\PIPE\ for remote communications. It is possible to have multiple servers having each his own pipe value. Client must select the server for connect by specifying either same value for local connect or \\SERVER\server_pipe_value for remote.
connections | decimal | 2 | The number of simultaneous connections for server to accept. The value must be 2 or greater.
priority.class | decimal | 3 | Pipe reading thread priority class.
priority.delta | decimal | 0 | Pipe reading thread priority delta.

## Technical description

The plugin is extending infobus address space to remote instances. Remote instance infobus variable can be addressed by adding <plugin>.pipes.<pipenumber>. to beginning, where <plugin> is remote control plugin instance name and <pipenumber> is connection number (0 for client, client number for server). Please note that connection is duplex and messages can be sent both from client to server and from server to client.

For example to shutdown remote instance from console you must issue the following command:
>exit:remote.pipes.0.plugman

To list remote variables
>var_list:remote.pipes.0
(In case where only <plugin>.pipes.<pipenumber> is used message is sent broadcast at remote instance).

Here is what happens on sending var_list to remote.pipes.0 (let client's remote plugin instance be named "remote", server's instance "serverremote" and the client has number 5):

Client:
Message "var_list" from "main.console" to "remote.pipes.0" with value "" is sent.
Plugin remote strips prefix "remote.pipes.0" and sends message to 0 pipe.

Server:
Plugin serverremote received message from client #5. It adds prefix and sends message "var_list" from "serverremote.pipes.5.main.console" to "" (broadcast) with value "".
Plugin ppp receives this message and sends data back with message "notify_var_type" from "ppp" to "serverremote.pipes.5.main.console" with value "342543" (value may be different)
Plugin serverremote strips prefix "serverremote.pipes.5" and sends message to 5 pipe.

Client: Plugin remote received message from pipe #0. It adds prefix and sends message "notity_var_type" from "remote.pipes.0.ppp" to "main.console" with value "342543".
The message is displayed at console.

Notice: Since message must have "<plugin>.pipes.<pipenumber>" prefix, any tree listing messages that don't have such prefix WON'T return remote data.

## Configuring HOW-TO

To use remote control you must configure:

1. Server (usually by adding remote control to already working configuration). To do this:
   a)Add new section "remote" to you configuration file. Note that this must be new section. If section of such a name already exists, you must use any other name (and replace "remote" latter with new name).
   b)Section must look like:

       [remote]
       load=pl_rcon:REMOTE_PIPE
       server=yes

   c)You may also add other pipe name by adding "pipe=pipename" variable if you need to run multiple servers (Each must have unique pipe name).
   d)Add line "bind=rmt_pipe:remote.1" to the [ppp] section.
2. Client. Client's configuration file must look like:

       ;------client.cfg-------
       [ppp]
       load=pl_rcon:REMOTE_PIPE
       server=no
       ;----------------------

   You can also add pipe variable. To access server from remote computer, add "pipe=\\SERVER\PIPE\SAFEFIRE\RCON" (or another pipe name).

That's all. Now you can use you "server" in 3 ways:

1. Console mode. Start "sfcon -Cclient.cfg"
2. Using sfkill (either execulable or script version).
3. Using sfcgi (must have unmodified pipe name).

## SFKILL

SFKILL is utility to stop SafeFire gracefully. Since it is using remote control, running instance must have remote control enabled in server mode.

Usage: "sfkill [pipename]". Optional parameter pipename can be used to specify alternative pipe name. (for example: "sfkill \\SERVER\PIPE\SAFEFIRE\RCON")

SFKILL is provided in two independant equvalent versions:
a)SFKILL.EXE - UI module with very limited functionality (only send kill message and exit)
b)SFKILL.CMD/SFKILL.CFG/SFKILL.SCR set (located in doc\samples) - does exactly the same in rexx and can be used as example for "send command and exit" scripts. It uses sfcli.exe as UI module.

Return to documentation index | SafeFire Links (C) Link Guard Solutions 1999, 2000