## SafeFire Links

### v1.3a

# Plugin Reference

## PL_PPP plugin library

This plugin library allows user to establish communications using Point To Point protocol, attach to OS/2 TCP/IP stack (by creating PPP devices) and use some PPP NCPs over established connection.

### PPPPort plugin

This plugin allows user to create PPP connection over Asynchronous device (like Modem, COM port (using null-modem cable) or ISDN adapter (using COM emulation software)).

It has two stream packs described below (both are operating in Single Connection Mode - only binding to 0 connection index is allowed):

1. IO

   > Packets received from this stream pack will be transferred over PPP connection; Packets received from PPP connection will be put to this stream pack.

   > Stream will be set UP after establishing of connection and put DOWN on connection termination.

2. DOD

   > Packets received from this stream pack will trigger Dial On Demand functions.

   > Stream pack will be used only if DOD is enabled

   > Stream will be set UP on startup or after connection termination and put DOWN after establishing of PPP connection.

It processes following configuration variables:

Name | Type | Default Value | Description
--- | --- | --- | ---
priority.* |  |  | Communication thread priority settings
port.* |  |  | Communication port and dialing settings
port.name | string | com1 | Communication Port name. Either local (i.e. "com1") or remote (i.e. "\\server\comshare")
port.speed | decimal | 38400 | Baud Rate port will be locked to
port.rtscts | boolean | no | If to setup port for hardware flow control
port.dcd | boolean | no | If to use DCD as Carrier Detect signal
port.dtr | boolean | no | If to use DTR to hang up connection
port.share | boolean | yes | If to share port with other programs.
script and other |  |  | Regular connection dialer settings
callback.* |  |  | Callback settings
callback.mode | list | NONE | Mode of callback operations. Possible values are: "NONE" (disabled), "CLIENT" (client mode), "SERVER" (server mode). Note: You must use server authentication with authorization database to use callback server mode.
callback.cbcp.recv.timeout | time (seconds) | 10 | How long to wait for successful completion of CBCP negotiations before closing connection on client
callback.client.operation | decimal | 6 | Callback operation as specified in RFC. 6 means CBCP callback mode. (For modification by advanced users only)
callback.client.location | string |  | Callback location for non-CBCP callback modes. (For modification by advanced users only)
callback.client.phone | string |  | User's phone number. Used in CBCP mode only. Set if either server don't know your phone number or has the list of your numbers.
callback.client.delay | time(seconds) | 10 | Delay before redialing proposed for server
callback.chat.* |  |  | Callback dialer settings. They must be set to perform callback call (or wait for callback from server in client mode). Proposed client setting are: `callback.chat.script.mode=SLATTACH callback.chat.script.timeout=120 callback.chat.script=ATZ OK \c RING ATA CONNECT callback.chat.modem.redial.min=0 callback.chat.modem.redial.max=0`
dod.* |  |  | Dial On Demand Settings
dod.enabled | boolean | no | If DOD enabled
dod.address | IP | 10.0.3.1 | "This side" address of fake interface
dod.peeraddress | IP | 10.0.3.2 | "Other side" address of fake interface
* |  |  | General PPP protocol settings

### PPTP plugin

This plugin allows user to create PPP connection over existing IP connection using PPtP. SFLinks becomes PPtP PNS in this case.

It has two stream packs described below (both are operating in Single Connection Mode - only binding to 0 connection index is allowed):

1. IO

   > Packets received from this stream pack will be transferred over PPP connection; Packets received from PPP connection will be put to this stream pack.

   > Stream will be set UP after establishing of connection and put DOWN on connection termination.

2. DOD

   > Packets received from this stream pack will trigger Dial On Demand functions.

   > Stream pack will be used only if DOD is enabled

   > Stream will be set UP on startup or after connection termination and put DOWN after establishing of PPP connection.

It processes following configuration variables:

Name | Type | Default Value | Description
--- | --- | --- | ---
priority.* |  |  | Communication thread priority settings
pptp.* |  |  | PPtP connection settings
pptp.serverhosts | string |  | PPtP PAC DNS names or IP addresses separated by spaces
pptp.serverport | decimal | 1723 | PPtP PAC TCP port common for all PACs
dod.* |  |  | Dial On Demand Settings
dod.enabled | boolean | no | If DOD enabled
dod.address | IP | 10.0.3.1 | "This side" address of fake interface
dod.peeraddress | IP | 10.0.3.2 | "Other side" address of fake interface
* |  |  | General PPP protocol settings

### PPPStack plugin

This plugin allows user to create serial-type interface in the OS/2 TCP/IP stack.

It has one stream packs described below (operating in Single Connection Mode - only binding to 0 connection index is allowed):

1. IO

   > Packets received from this stream pack will be sent to TCP/IP stack; Packets received from TCP/IP stack will be put to this stream pack.

   > Stream will be set UP on startup and put DOWN on exit.

It processes following configuration variables:

Name | Type | Default Value | Description
--- | --- | --- | ---
pppnum | decimal | 0 | Interface number
pppfixed | boolean | no | If set to yes, only creation of pppnum interface is possible. If no, any free interface number can be used (yet pppnum will be tried first)
defaultroute | boolean | no | If to setup default route to this interface on connect
proxyarp | boolean | no | If to setup proxy arp entry to this interface on connect
prefix | string | ppp | Interface name prefix. Full name is concatenation of prefix and pppnum
netmask | IP | 255.255.255.255 | Netmask to be set up for the interface
loopback.mode | decimal | 2 | Type of operations with packets for this side got from TCP/IP stack. Possible values are: 0 - send it to peer 2 - send back to stack 1 - both
priority.* |  |  | Stack reading thread priority settings

### CCP plugin

This filter plugin provides CCP (compression control protocol) functionality for PPP users.

Plugin is operating in Multiple Connection Mode:

> You may compress multiple streams by assigning connection index to each stream. You will get packed DATA.x packets from COMPRESSED.x

> Note: All streams are using same compression database - so you must have same set connected at peer to ensure correct compression.

It has two stream packs described below.

1. DATA

   > Packets received from this stream pack will compressed and sent to COMPRESSED stream pack; Decompressed packets will be put to this stream pack.

   > Each Stream will be set to the same state as peer's COMPRESSED stream state.

2. COMPRESSED

   > Packets received from this stream pack will decompressed and sent to DATA stream pack; Compressed packets will be put to this stream pack.

   > Each Stream will be set to the same state as peer's DATA stream state.

It has no configuration variables.

### PPPoE plugin

This plugin allows user to create PPP connection over Ethernet segment

It has two stream packs described below (both are operating in Single Connection Mode - only binding to 0 connection index is allowed):

1. IO

   > Packets received from this stream pack will be PPPoE-encapsulated and sent to Ethernet; Packets received from PPPoE connection will be put to this stream pack.

   > Stream will be set UP after establishing of connection and put DOWN on connection termination.

2. ETHERNET

   > Packets received from this stream pack will be processed as PPPoE packets Encapsulated PPPoE packets will be put to this stream pack.

   > Stream will be set UP on startup DOWN on exit.

It processes following configuration variables:

Name | Type | Default Value | Description
--- | --- | --- | ---
pppoe.server | boolean | no | If to work as PPPOE server (no - means client mode)
pppoe.servername | string |  | PPPoE server name. Must be specified in server mode. If specified in client mode, only connection to the indicated server will be allowed
pppoe.servicename | string |  | PPPoE service name. Must be specified in server mode. If specified in client mode, only connection to the server with indicated service will be allowed
pppoe.closeunknown | boolean | yes | If to close (by sending terminate packet) unknown PPPoE connections. Will ignore unknown packets if set "no"
* |  |  | General PPP protocol settings

## PL_ALIAS plugin library

This plugin library allows user to use Name Address Translation (other name is IP Masquerading) services.

### NAT plugin

This filter plugin provides dynamic NAT and Port Mapping functionality for TCP/IP users.

Plugin is operating in Multiple Connection Mode:

> You may masquerade multiple streams by assigning connection index to each stream.

> Note: All streams are using same TCP connections database.

It has two stream packs described below.

1. STACK

   > Packets received from this stream pack will masqueraded (translated) and sent to PORT stream pack; Demasqueraded packets will be put to this stream pack.

   > Each Stream will be set to the same state as peer's PORT stream state.

2. PORT

   > Packets received from this stream pack will be demasqueraded and sent to STACK stream pack; Masqueraded packets will be put to this stream pack.

   > Each Stream will be set to the same state as peer's STACK stream state.

It processes following configuration variables:

Name | Type | Default Value | Description
--- | --- | --- | ---
map | String |  | Add port mapping rule. Syntax is described below. Note: This variable operates in multiple-instance mode (i.e. you can define multiple mappings, all of them will be used, not only last one)
enabled | boolean | yes | If disabled, plugin will function as null filter
defragment | boolean | yes | If to process fragmented packets
forward_ignored | boolean | no | If to allow packets that was not processed to pass through NAT engine.
private_net | boolean | no | Only packets from so called "private space" will be masqueraded and demasqueraded. All other packets will go through as is, without changes. Refer to Thesaurus for more information.

#### Port Mapping rule syntax

Port mapping can work in two modes: port-to-port and address-to-address.
In port-to-port mode each rule redirects packets coming to specified port or range of ports into port or range of ports at other IP address.
In address-to-address mode each rule redirects all IP packets coming to specified IP address into other IP address.
Each rule has following syntax:

    map = src_addr:src_port,dst_addr:dst_port [count] [proto]

where:

src_addr | Destination address of the packets that will be mapped. Address 0.0.0.0 used here will be replaced by current dynamically assigned IP address.
src_port | Destination port of the packets that will be mapped. For address-to-address mode can be set to 0.
dst_addr | IP address in of host in internal network to which packets will be forwarded during port mapping.
dst_port | New destination port of the packets after mapping. For address-to-address mode can be set to 0.
count | Optional number of ports to map. If greater than one then sequential ports starting from specified will be mapped. For example, following rule
    map=0.0.0.0:80,192.168.1.10:8080 10
will map packets coming to dynamically assigned IP and port 80 thru 89 to address 192.168.1.10 and ports 8080 thru 8089. If omitted then count assumed equal to 1.
proto | One of the: udp, tcp, both or all. both is default value and means that UDP and TCP packets will be processed. all turns rule in address-to-address mode.

## PL_FLT plugin library

This plugin library allows user to use different firewall functions.

### FILTER plugin

This filter plugin provides IP packet filter functionality to the user.

Plugin is operating in Multiple Connection Mode:

> You may filter multiple streams by assigning connection index to each stream.

> Note: All streams are using same filter rules database.

It has two stream packs described below.

1. STACK

   > Packets received from this stream pack will be filtered and sent to PORT stream pack; Accepted packets from PORT stream pack will be put to this stream pack.

   > Packets from this stream will be marked outgoing.

   > Each Stream will be set to the same state as peer's PORT stream state.

2. PORT

   > Packets received from this stream pack will filtered and sent to STACK stream pack; Accepted packets from STACK stream will be put to this stream pack.

   > Packets from this stream will be marked incoming.

   > Each Stream will be set to the same state as peer's STACK stream state.

It processes following configuration variables (For details see Packet Filter Guide and Reference):

Name | Type | Default Value | Description
--- | --- | --- | ---
enabled | Boolean | no | If disabled, plugin will function as null filter
rule | String |  | Add filtering rule

## PL_LAN plugin library

This plugin library implements different Gateway modules that provides access to NDIS stack.

### PROTOCOL plugin

This External Device gateway creates virtual NDIS protocol that (while attached to Network Interface Card) can catch packets from network and send packets to network.

Plugin is operating in Single Connection Mode - only binding to the 0 index of stream pack is allowed:

It has one stream pack described below.

1. IO

   > Packets received from this stream pack will be sent to network as Ethernet packets; Packets received from network will be put to this stream pack.

   > Stream will be set UP on start up and put DOWN on exit.

It processes following configuration variables:

Name | Type | Default Value | Description
--- | --- | --- | ---
drivername | string | SFPROT$ | Name of the loaded instance of SafeFire Protocol driver. for details on loading driver see PPP over Ethernet Configuration Guide.
protocol | string |  | This is multiple instance configuration variable - this means that all variables will be used, not only the last one (Only first 16 variables will be used for now). This variables defines packets belonging to which protocol to catch Note: defining too wide range, like "0 0" may prevent other protocol drivers connected to same network card to receive packets. Format: `protocol=number mask` where rule for defining if packet must be intercepted is following: `protocol & mask == number`, where `protocol` is packet's protocol number, "&" is bit and, "==" is Boolean equal function. Note All values above should be specified as hexadecimal numbers. Examples: protocol = 0 0 All packets protocol = 8864 FFFF Only packets of 8864 protocol protocol = 8800 FF00 Packets of protocols from 8800 to 88FF
fastmode | boolean | yes | Enables packet queuing. This greatly increases performance when we have many small packets
dump.receive | boolean | no | If to dump contents of all received packets to log
dump.send | boolean | no | If to dump contents of all sent packets to log
read.priority.class | decimal | 4 | A priority class of the reading thread
read.priority.delta | decimal | 5 | A priority level of the reading thread
write.priority.class | decimal | 4 | A priority class of the writing thread
write.priority.delta | decimal | 0 | A priority level of the writing thread
boostwrite.priority.class | decimal | 3 | (fastmode only) A priority class of the boosted writing thread
boostwrite.priority.delta | decimal | 10 | (fastmode only) A priority level of the boosted writing thread

### ADAPTER plugin

You may create virtual SafeFire MAC which will transfer data via virtual NDIS protocol to a real MAC. When TCP/IP is bound to this virtual MAC SFPP/Links works as transforming engine for all TCP/IP packets related to this lanX interface. So for the simple firewall you should create the following binding scheme: Adapter-Filter-Protocol.

Plugin is operating in Single Connection Mode - only binding to the 0 index of stream pack is allowed:

It has one stream pack described below.

1. IO

   > Packets received from this stream pack will be sent to OS/2 network stack. In the usual configuration they will be transferred to a corresponding lanX interface; Packets received from OS/2 stack will be put to this stream pack.

   > Stream will be set UP on start up and put DOWN on exit.

It processes following configuration variables:

Name | Type | Default Value | Description
--- | --- | --- | ---
drivername | String | SFMAC$ | Name of the loaded instance of SafeFire Firewall MAC driver. The second instance has name "SFMAC2$" and so on. For details on loading driver see PPP over Ethernet Configuration Guide
lan.num | decimal | 255 | Explicit number of lanX interface. When it is more than 8 the plugin will try to determine it automatically. You'll need this parameter when an interface was not configured before plugin's start
lan.drop | boolean | no | Drop lanX interface with all its routes when plugin goes down
fastmode | boolean | yes | Enables packet queuing. This greatly increases performance when we have many small packets
dump.receive | boolean | no | If to dump contents of all received packets to log
dump.send | boolean | no | If to dump contents of all sent packets to log
read.priority.class | decimal | 4 | A priority class of the reading thread
read.priority.delta | decimal | 5 | A priority level of the reading thread
write.priority.class | decimal | 4 | A priority class of the writing thread
write.priority.delta | decimal | 0 | A priority level of the writing thread
boostwrite.priority.class | decimal | 3 | (fastmode only) A priority class of the boosted writing thread
boostwrite.priority.delta | decimal | 10 | (fastmode only) A priority level of the boosted writing thread

## PL_OVPN plugin library

The OpenVPN related code.

### OpenVPN plugin

This plugin incorporates the OpenVPN 2.1_rc1 code to create OpenVPN tunnels. It have to be used in conjunction with pl_lan:Adapter plugin to bind to a system TCP/IP stack. Of course various filters like NAT may be inserted in the chain also. There is no support for TUN device as pppX interface. Both (TAP and TUN) modes are implemented over lanX interface like TAP-Win32 adapter.

To generate TLS certificates you'll need the openssl utility. No special version restriction for it. For example you can take it here.

Plugin is operating in Single Connection Mode - only binding to the 0 index of stream pack is allowed.

It has one stream pack described below.

1. IO

   > Packets received from this stream pack will be encrypted and be sent via OpenVPN connection; Packets received from OpenVPN connection will be decrypted and be put to this stream pack.

   > Stream will be set UP on start up and put DOWN on exit.

It processes following configuration variables:

Name | Type | Default Value | Description
--- | --- | --- | ---
openvpn.config | string | sflinks.ovpn | Name of the OpenVPN config file. Conlsult the original man page about details how to write it
priority.class | decimal | 4 | A priority class of the network thread
priority.delta | decimal | 5 | A priority level of the network thread

### OVPNGENK utility

This utility generates static OpenVPN key. It makes the same as original 'openvpn [ --genkey ] [ --secret file ]'. Consult the man page about details.

## Common configuration variables

Here listed configuration variables that are common for multiple plugins or used multiple times in single plugin.

To make up full variable name concatenate start name from referencing table (without *) and name from the tables below.

Example:

> PL_PPP:PPPPORT plugin has priority.* reference to priority table. Priority table has class variable. Full name of this variable will be priority.class.

1. Priority settings.
   Used in PL_PPP:PPPPORT and PL_PPP:PPPSTACK.

   Name | Type | Default Value | Description
   --- | --- | --- | ---
   class | decimal | 3 | Priority class of the thread
   delta | decimal | 0 | Priority level of the thread

2. Dialer settings.
   Used in PL_PPP:PPPPORT.

   Name | Type | Default Value | Description
   --- | --- | --- | ---
   script | string |  | Connection script parameter
   script.mode | list | DIAL | Type of connection script used. Possible values: DIAL, SLATTACH, REXX. See Dialing scripts to get details
   script.timeout | time(seconds) | 45 | Connection script single dial timeout
   script.guard.timeout | time(seconds) | 300 | Connection script timeout
   phones | string |  | Phones list (DIAL mode only)
   modem.init | string | ATZ | Modem init string (DIAL mode only)
   modem.dial | string | ATD | Modem dial prefix (DIAL mode only)
   modem.redial.min | time(seconds) | 5 | Minimal delay between calls
   modem.redial.max | time(seconds) | 20 | Maximum delay between calls
   modem.connect | string | CONNECT | Modem "CONNECT" response (DIAL mode only)
   modem.busy | string | BUSY | Modem "BUSY" response (DIAL mode only)
   modem.nocarrier | string | NO CARRIER | Modem "NO CARRIER" response (DIAL mode only)
   modem.nodialtone | string | NO DIALTONE | Modem "NO DIALTONE" response (DIAL mode only)
   modem.ring | string | RING | Modem dialing indicator (DIAL mode only)

3. General ppp settings.
   Used in PL_PPP:PPPPORT and PL_PPP:PPPOE.

   Name | Type | Default Value | Description
   --- | --- | --- | ---
   restart | decimal | -1 | How many times to retry connection. -1 mean indefinite.
   ip.* |  |  | Internet Protocol settings
   ip.address | IP | 0.0.0.0 | Use as my IP. Do not agree for other. Request from peer if 0
   ip.peeraddress | IP | 0.0.0.0 | Send as peer's IP. Use peer-provided if 0. Note: If multiuser authentication is enabled, PPP will not use this variable.
   ip.dns.primary | IP | 0.0.0.0 | Send to peer as Primary DNS value (if not 0)
   ip.dns.secondary | IP | 0.0.0.0 | Send to peer as Secondary DNS (if not 0)
   ip.restart | time(seconds) | 3 | How often to repeat IPCP requests
   ip.max.configure | decimal | 10 | How many IPCP requests to send before closing connection
   lcp.* |  |  | LCP Protocol settings For modification by advanced users only
   lcp.recv.ac | boolean | yes | If allow Address and Protocol field compression negotiations (receive)
   lcp.send.ac | boolean | yes | If allow Address and Protocol field compression negotiations (send)
   lcp.recv.accm | integer | 0 | Receiving ACCM to negotiate
   lcp.send.accm | integer | 0 | Sending ACCM to negotiate
   lcp.recv.mru | integer | 1500 | Default Maximum Receive Unit to negotiate. Note: This and next two setting can be changed by the plugin at runtime to work in the existing environment.
   lcp.recv.maxmru | integer | 3500 | Maximal MRU to allow
   lcp.send.mtu | integer | 1500 | Maximum Tranfer Unit to negotiate
   lcp.restart | time (seconds) | 3 | LCP control packets timeout
   lcp.max.terminate | integer | 2 | How many LCP Terminate packets to send without acknowledgment before closing connection
   lcp.max.configure | integer | 10 | How many LCP Configure packets to send without acknowledgment before closing connection
   auth.* |  |  | Authentication settings
   auth.authreq | boolean | no | If to require client to authenticate (enable for server mode)
   auth.server.* auth.client.* |  |  | All this options can be specified in two ways: General option - will be used for all authentication protocol. One must use variable names for this table Protocol-specific option - will be used for specified authentication protocol only. One must add protocol name and a point after "auth.server." or "auth.client." part. Example: `auth.server.chap.enabled=no` Using this feature you can specify different options for different protocol. I.E. to have one authentication database for PAP and other for CHAP. Example: "auth.server.clientname" will be passed to all protocols while "auth.server.pap.clientname" only to PAP. Current authentication protocol list includes PAP, CHAP, MSCHAP, MSCHAPv2. Note: All CHAPs must be treated as a completely independent protocols. This means that you can have MSCHAP enabled while CHAP is disabled.
   auth.server.enabled | boolean | yes | If the protocol is enabled
   auth.server.servername | string |  | This server's name. (Used only by all CHAPs)
   auth.server.clientname | string |  | User's name. This option won't be used if authbase is specified
   auth.server.clientpass | string |  | User's password. This option won't be used if authbase is specified
   auth.server.authbase | string |  | Authorization database module and it's parameters
   auth.client.enabled | boolean | yes | If the protocol is enabled
   auth.client.servername | string |  | Check server name before passing passwords. (Used only by all CHAPs)
   auth.client.clientname | string |  | Your user name
   auth.client.clientpass | string |  | Your password
   timeout.* |  |  | Connection timeout settings
   timeout.idle.time | time(seconds) | -1 | How long to wait after the last packet before closing connection. -1 means timer disabled
   timeout.idle.exit | boolean | no | If to exit SafeFire Links after closing idled connection
   timeout.idle.notify.start | time(seconds) | 0 | When to start idle timeout notification (time before closing connection)
   timeout.idle.notify.period | time(seconds) | 0 | How often to repeat notifies.
   timeout.connection.time | time(seconds) | -1 | Maximum connection period. -1 means timer disabled
   timeout.connection.exit | boolean | no | If to exit after closing "long" connection
   timeout.connection.notify.start | time(seconds) | 0 | When to start connection timeout notifications (time before closing connections)
   timeout.connection.notify.period | time(seconds) | 0 | How often to repeat notifications
   timeout.echo.time | time(seconds) | 10 | Minimal time from the last packet received to wait for sending echo packet. -1 means timer disabled
   timeout.echo.period | time(seconds) | 10 | Period to retry sending echo packets
   timeout.echo.retry | Integer | 5 | How many unanswered echo packets to send before closing connection

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