Overview of FWCtl - command-line FireWall ConTroL tool

This Knowledge Base article applies to:

Clavister FWCtl (all versions)

The word Firewall can be replaced with "Security Gateway" to apply to later releases (CorePlus 8.70.00 and newer, as well as 8.65 and 8.67 series).

FWCtl is a tool to perform various automated or batch firewall control tasks, such as periodic statistics polling, automated configuration changes, etc. It is currently available for the Win32 command-line console and Linux x86.

This overview describes FWCtl. It works with CorePlus version 8 management Datasources, and adds the following features from the previous version that worked with v7 Datasources:

Topics covered in this document


Datasource management

Under windows, FWCtl will use the same datasource settings that the Firewall Manager uses. These settings are stored in the registry, under HKEY_CURRENT_USER.

Under unix, FWCtl stores these settings in ~/.fwctlrc.

--adddsn - Add (attach) a new datasource

Syntax: --adddsn <dsn name> "<connect string>"
Example: fwctl --adddsn mydsn "c:\path\to\my\datasource"

Note that adddsn does not verify that the given directy actually contains firewalls or namespaces; only that it exists.

--rmdsn - Remove (detach) an existing datasource

Syntax: --rmdsn <dsn name>
Example: fwctl --rmdsn mydsn

Note that rmdsn only disconnects fwctl from the datasource; it does not delete the actual contents.

--listdsn - List attached datasources

Syntax: --listdsn [--plain] [-d "<delim>"]
Examples:
  • fwctl --listdsn
    Name       Status   Path
    Default    Enabled  d:\Firewall Manager 8\Default
    Samples    Enabled  d:\Firewall Manager 8\Samples
    mydsn      Enabled  c:\path\to\my\datasource
  • fwctl --listdsn -d ";"
    Name;Status;Path
    Default;Enabled;d:\Firewall Manager 8\Default
    Samples;Enabled;d:\Firewall Manager 8\Samples
    mydsn;Enabled;c:\path\to\my\datasource

--list (-l) - List all firewalls in all attached datasources

Syntax: --list [--plain] [-d "<delim>"] ["<pattern>"]
Example:
  • fwctl --list
    Name            IP Address    Status     Core      Type
    Default:mygw    192.168.0.1   ACTIVE     8.00.04   VPN
    mydsn:test      127.0.0.1     INACTIVE

--dumpdsn (-d) - Display the contents of a DSN in a tree view, much the same as the Security Editor tree view in the Firewall Manager

Syntax: --dumpdsn <dsn name>
Example: fwctl --dumpdsn mydsn



Basic communication

--console (-c) - Attach to the firewall console

Syntax: --console [-t <seconds>] <firewall>
Examples:
  • fwctl --console mygw
    Attaches to the firewall console, just like in the Firewall Manager.
  • echo stats | fwctl --console -t 2 mygw > results.txt
    Send the console command "stats" to the firewall and store the output in the file "results.txt". The "-t 2" switch means that the process has 2 seconds to complete before fwctl disconnects and exits.
Note that <firewall> can be extended further in all commands that take a firewall name argument, including "--console":
  • fwctl --console mydsn:mygw
    Pinpoints the firewall "mygw" in the datasource "mydsn".
    Useful for safer scripting as it won't be fooled by entries added to other datasources.
  • fwctl --console x:\path\to\mygw.efw
    Directly uses the firewall defined by "mygw.efw" without having to actually attach to the datasource that it resides in.
Use ctrl+c to exit from the console. (Or, in scripts, the "-t" switch).


--rtlog (-r) - Display the real-time log of the firewall

Syntax: --rtlog <firewall>
Examples:
  • fwctl --rtlog mygw
    Displays the real-time log. Abort by hitting [Esc] or Ctrl+C.
  • fwctl --rtlog mygw | find "srcip=1.2.3.4" > results.txt
    Puts all real-time log entries containing the source IP address "1.2.3.4" in the file "results.txt".
Use ctrl+c to exit from the real-time log viewer.


--ping (-p) - "Ping" the firewall - retreive uptime and basic stats

Syntax: --ping [-t <timeoutsecs>] <firewall>
Example:
  • fwctl --ping -t 7 mygw
    Core version    : 8.00.04
    Uptime          : 96393 seconds
    Config version  : 278
    Modules running : VPN
The timeout defaults to 15 seconds. The ping, which uses UDP port 999, is retransmitted every three seconds until the timeout expires or a response is received.



File upload/download
--cfgupload (-u) - Upload a configuration file to the firewall

Syntax: --cfgupload [-v <version> | -f <file>] <firewall>
Examples:
  • fwctl --cfgupload mygw
    Upload the most recent configuration stored in the management datasource.
  • fwctl --cfgupload -v 123 mygw
    Upload version 123 from the management source.
  • fwctl --cfgupload -f x:\path\to\config.txt mygw
    Upload the contents of the given file.
Note that the configuration is only uploaded, not activated.
A complete configuration upload procedure:
  • fwctl --cfgupload mygw
    fwctl --reconfigure mygw

--cfgdownload (-w) - Download the configuration file from the firewall

Syntax: --cfgdownload [-f <file>] <firewall>
Examples:
  • fwctl --cfgdownload mygw
    Downloads the configuration and stores it in the management datasource.
  • fwctl --cfgdownload -f x:\path\to\mycfgfile.txt
    Puts the downloaded configuration in a separate file, rather than storing it in the management datasource.

--coreupload - Upload a new firewall core to the firewall

Syntax: --coreupload <core file> <firewall>
Examples:
  • fwctl --coreupload x:\path\to\fwc-8.00.04-novpn.cfx mygw
    fwctl --restart --nobidir mygw

  • fwctl --cfgupload mygw
    fwctl --coreupload x:\path\to\fwc-8.00.04-full.cfx mygw
    fwctl --restart mygw

--fileupload - Upload an arbitrary file to the firewall

Syntax: --fileupload "<source>" "<destination>" <firewall>
Example: fwctl --fileupload x:\path\to\fwldr-1.01.cfx fwldr.cfx mygw

Note that, while it is possible to do so, it is not recommended to upload "fwcore.cfg" nor "fwcore.cfx" this way. For these files, "--cfgupload" and "--coreupload", respectively, are the recommended methods.



More communications commands
--reconfigure (-e) - Instruct the firewall to re-read its configuration

Syntax: --reconfigure <firewall>
Example: fwctl --reconfigure mygw

Using fwctl --reconfigure is not quite the same as typing "reconfigure" on the firewall console. In addition to instructing the firewall to re-read its configuration, fwctl will also attempt to reconnect to the firewall when the new configuration has been parsed, and confirm that bi-directional management communication is possible using the new configuration. This is what the Firewall Manager does when it uploads configurations.


--restart - Instruct the firewall to exit the firewall core (and restart)

Syntax: --restart [--nobidir] <firewall>
Examples:
  • fwctl --restart --nobidir mygw
    Instructs the firewall to exit the firewall core - the boot loader will restart it. Does not wait for completion.
  • fwctl --restart mygw
    Like above, but waits for the firewall to come back up, and performs bi-directional communication verification the same way that --reconfigure does.

--reboot - Instruct the firewall to perform a full reboot

Syntax: --reboot <firewall>
Example: fwctl --reboot mygw

Performing a full reboot of a firewall is normally not necessary. An obvious exception to this rule is when the boot loader (fwldr.cfx) has been upgraded.


--changekeys - Negotiate new keys to use for remote management of a firewall

Syntax: --changekeys <firewall>
Example: fwctl --changekeys mygw

Note that you do not specify what you want the keys to be. They are generated using random data from fwctl and from the firewall itself. The negotiated keys are automatically stored in the firewall (in the binary file security.bin), and in the local management database (in e.g. mygw.efw).


--stats (-s) - Perform real-time statistics polling

Syntax 1: --list [-d "<delim>"] <firewall>
Syntax 2: [--count <n>] [--interval <secs>] [-d "<delim>"] [--units] [--nohdrs] [--rawcounters] <entries> <firewall>

Examples:

  • fwctl --stats --list mygw
    Name                          Unit      Type   Description
    fwctl                                          FWCtl
    fwctl/localtime                                  Local Time
    fwctl/localtime/rfc3339                 Gauge      Local time
    [...]
    core                                           Firewall
    core/conns                              Gauge    Conns
    core/bufusage                 %         Gauge    Buf use
    core/fwdpps                   pps       Count    Forwarded pps
    core/fwdbps                   bps       Count    Forwarded bps
    core/cpuload                  %         Gauge    CPU
    core/uptime                   seconds   Gauge    Uptime
    [...]

  • fwctl --stats --count 2 --interval 3 -d "\t"   (contd.)
      fwctl/utc/iso core/cpuload core/fwdbps mygw
    UTC time (iso format)   CPU     Forwarded bps
    2003-02-17 08:35:45     3       426526
    2003-02-17 08:35:48     1       121826

Note that both "Gauge" and "Count" type values are normally displayed as gauges. That is, for counters, you will see the difference between two polls, divided by the polling interval. With the "--rawcounters" switch, the counters will be displayed without postprocessing. This is useful for e.g. feeding values to graphing and statistics tools like rrdtool.




Configuration management
--cfginfo - Display database information about a firewall configuration

Syntax: --cfginfo [-v <version>] <firewall>
Examples:
  • fwctl --cfginfo mygw
    Version: 312 (312)
    Date: 2003-02-04 08:29
    User: alice
    Comments:
    Allowed anti-virus distribution server on intnet to FTP to new vendor definition distribution server
  • fwctl --cfginfo -v 311 mygw
    Version: 311 (312)
    Date: 2003-01-27 13:15
    User: bob
    Comments:
    Increased std-out per-user limit from 256Kbps to 512Kbps

--checkout (-o) - Mark a firewall's configuration as "checked out"

Syntax: --checkout <firewall>
Example: fwctl8 --checkout mygw

"Checking out" the configuration of a firewall means that it is locked for editing by you. No one else is allowed to edit it. It can only be checked back in by yourself, using the same tool (fwctl vs. fwmgr), on the same computer.

See working with configurations for more information.

--printcfg (-t) - Print the configuration file of a firewall on screen

Syntax: --printcfg [-v <version>] <firewall>
Example: fwctl8 --printcfg mygw > mygw-config.txt

See working with configurations for more information.

--checkin (-i) - Check a firewall configuration back in

Syntax: --checkin [-c "<comments>"] <file> <firewall>
Example: fwctl8 --checkin -c "some changes" x:\path\to\config.txt mygw

The configuration you wish to check in must have previously been checked out by you, using fwctl, on the same computer. After the configuration has been checked back in, others are allowed to check it out and make changes to it.

See working with configurations for more information.

--undocheckout - Undo a "check out" operation

Syntax: --undocheckout <firewall>
Example: fwctl8 --undocheckout mygw

See working with configurations for more information.

--checkoutlist - List checked-out firewalls in all datasources

Syntax: --checkoutlist [-u <user>] [-d "<delim>"]
Example: fwctl8 --checkoutlist -u bob



Getting started

This small guide assumes that fwctl is already downloaded, and perhaps also added to your system path.

You may need to attach to the datasources you want to work with. If you are using fwctl on the computer where you use Firewall Manager, you can likely skip this step; fwctl uses the same datasource settings that the Firewall Manager does.

Use "--list" to see the list of firewalls available in your DSNs.

At this point, you'll be able to use all the basic communications commands like ping, console, etc. Also see working with configurations.

Working with configurations

The first thing you'll need to do is to check out the firewall configuration so that no one else can edit it simltaneously.

If this is done in an automated script, it may be useful to know that fwctl always returns proper return codes. If the check-out operation fails, the script will be able to tell by checking the return value of the command (i.e. checking "ERRORLEVEL" under windows and normal "if" clauses under unix). See notes on automation / scripting.

After this, you'll want a copy of the actual configuration to work with:

At this point, you can make changes to config.txt, or perhaps filter it and store the results in "newconfig.txt". If the (automatic) configuration editing procedure fails, you should use "--undocheckout", which removes the lock on the firewall configuration without committing any changes to the database.
When editing is done, save the changes with:

And then you'll want to upload the changes to the firewall and activate them:

This concludes the normal configuration management procedure.

At this point, we would like to note that it is entirely possible to forego the management database, and use only externally generated configurations through using the "-f" switch of cfgupload to upload arbitrary configuration files. Doing so, however, means that the firewall really cannot be managed through the firewall manager. The firewall manager always works with the data stored in the management database.



Notes on automation / scripting

FWCtl is designed with automated scripting in mind. Below are a few key points to keep in mind when using FWCtl in scripts.