|
 |
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:
- Understands check-in/check-out (protects against simultaneous editing
by several users).
- Adds access to the Clavister Firewall statistics interface.
- Can work directly with Firewall definition files (".efw" files)
without actually attaching to its datasource.
Topics covered in this document
- Datasource management
adddsn, rmdsn, listdns, list, dumpdsn
- Basic communication
console, rtlog, ping
- File upload/download
cfgupload, cfgdownload, coreupload, fileupload
- More communications commands
reconfigure, restart, reboot, changekeys, stats
- Configuration management
cfginfo, checkout, printcfg, checkin, undocheckout, checkoutlist
- Getting started
- Working with configurations
- Notes on automation / scripting
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.
fwctl --adddsn mydsn "c:\Program Files\Clavister\Firewall Manager\Default"
Use "--list" to see the list of firewalls available in your DSNs.
fwctl --list
Name IP Address Status Core Type
Default:mygw 192.168.0.1 ACTIVE 8.00.04 VPN
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:
-
fwctl --printcfg mygw > config.txt
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:
-
fwctl --checkin newconfig.txt mygw
And then you'll want to upload the changes to the firewall and activate them:
-
fwctl --cfgupload mygw
-
fwctl --reconfigure mygw
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.
It is always a good idea to check the process return codes, e.g.:
| Windows: |
:tryagain
fwctl --checkout mygw
if errorlevel 1 ( sleep 10 & goto tryagain )
|
| Unix shell: |
while ! fwctl --checkout mygw; do
sleep 10
done
|
Use the console "-t" switch, e.g.:
C:\> echo conn | fwctl --console -t 2 mygw
Welcome, ext:192.168.0.2:2497
Cmd> conn
State Proto Source Destination Tmout
-------- ------- ------------------------ ------------------------ ------
TCP_OPEN TCP ext:192.168.0.2:2497 core:192.168.0.1:999 262144
Cmd>
Connection closed.
|
Note that diagnostic messages such as "Connection closed." are not output
if you redirect the output to a file. They are only displayed if fwctl
is being run "interactive".
Use only ";" and "\t" separators in delimited output
If the ";" separator is used, fwctl will automatically replace any
occurence of ";" within the output fields to ",".
The "\t" (tab) separator is always safe. Output fields never contain tabs.
One exception is for "--stats", where it makes sense to use ":" separators,
since rrdtool wants colon separated input. If you use colon separators, avoid
outputting formatted times, e.g. fwctl/localtime/rfc3339,
which uses colons.
GNU (text) utilities under windows
Utilities like "sleep", "head" and "tail" are nearly
indispensible when writing automated batch scripts.
Pick up a copy at
http://unxutils.sourceforge.net/
|
