                    SafeFire PPP/Links version 1.1
                      remote control operations
                         READ ME file
                   (c) Link Guard Solutions Ltd.
                      http://www.lgs.kiev.ua

    SafeFire PPP/Links 1.1 includes Remote Control.
This documents describes how to enable this support in
given configuration.
    There are two options on using the support:
        - Console mode (see console.txt)
        - Web mode. Please download sfcgi to use this.

                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 new plugin library is introduced:
PL_SERV:REMOTE_PIPE with the next configuration variables:

server - Bool - def. no - if this instance will 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 - Bool - def. no - if connection must be established in
    the "startup" phase. Usefull for scripting. By default
    connection will be established in background.

waittime - time(seconds) - def 1 - Used in case when client tries to
    access server and server don'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 - Bool - def. no - if to retransmit broadcast messages.
    Please note that in any case timer messages won't be retransmitted.

syncwait - time(seconds) - def. 10 - how long to wait for responce to sync
    messages. This is used to signal deadlocks.

pipe - string - def. \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 decide which server to connect by specifying either same value
    for local connect or \\SERVER\server_pipe_value for remote.

connections - integer - def. 2 - Number of simultaneous connections for server
    to accept. The value must be 2 or greater.

priority.class, priority.delta (Def. 3,0) - Pipe reading thread priority.

                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
next 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
     broadcastat 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 stips 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 WONT 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_serv: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_serv: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. (ex. "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


