credit Blair and Tim with MacPorts and Homebrew maintainer status
[fwknop.git] / perl / legacy / fwknop / README.ACCESS
1
2 This file describes some common example configurations for the
3 /etc/fwknop/access.conf file.
4
5 1) Define parameters for accepting single-packet authorization messages
6    from any source IP address via libpcap.  Fwknop will reconfigure the
7    local iptables policy to allow access to SSHD (TCP port 22) for 30
8    seconds from the IP also specified in the packet.  This example probably
9    represents the best configuration for most needs:
10
11   SOURCE: ANY;
12   OPEN_PORTS: tcp/22;
13   DATA_COLLECT_MODE: PCAP;
14   KEY: myencryptkey;
15   FW_ACCESS_TIMEOUT: 30;
16
17 2) If you would like the fwknop client to specify which port is opened by
18    fwknopd through the firewall, then replace the OPEN_PORTS variable with
19    PERMIT_CLIENT_PORTS as follows:
20
21   SOURCE: ANY;
22   PERMIT_CLIENT_PORTS: Y;
23   DATA_COLLECT_MODE: PCAP;
24   KEY: myencryptkey;
25   FW_ACCESS_TIMEOUT: 30;
26
27 3) This example is identical to example 1) above, but now we add GPG keys
28    as an alternate encryption method.  The original symmetric key will
29    still be accepted, but only if an attempted GPG decrypt does not
30    succeed.  The GPG_REMOTE_ID is the key ID that the encrypted packet is
31    signed with by the fwknop client.  Note that using GPG keys requires
32    that the client key has been imported (and signed) into the
33    GPG_HOME_DIR key ring on the server side, and the server key has been
34    imported (and signed) into the GPG key ring on the client side. Because
35    the GPG password for the server key is put within the access.conf, the
36    server key should be specifically generated and used only for fwknop
37    server functions; it should not a valuable GPG key that is used for
38    things like personal email encryption. See the fwknop man page for
39    examples of how to use the GPG encryption method from the fwknop
40    command line on the client side. To match any GPG key, set
41    GPG_REMOTE_ID to ANY.  The GPG_AGENT_INFO variable is included for
42    reference if fwknopd is run in gpg-agent mode.
43
44   SOURCE: ANY;
45   OPEN_PORTS: tcp/22;
46   DATA_COLLECT_MODE: PCAP;
47   KEY: myencryptkey;
48   GPG_HOME_DIR: /root/.gnupg;
49   GPG_DECRYPT_ID: ABCD1234;
50   GPG_DECRYPT_PW: myGpgPassword;
51   GPG_REMOTE_ID: 1234ABCD;
52   GPG_AGENT_INFO: /tmp/gpg-n7jEPC/S.gpg-agent:18333:1;  ### only for gpg-agent
53   FW_ACCESS_TIMEOUT: 30;
54
55 4) This example is identical to example 1) above, but now we allow a
56    remote fwknop client to send a command to the fwknopd server (which it
57    will execute as root):
58
59   SOURCE: ANY;
60   OPEN_PORTS: tcp/22;
61   DATA_COLLECT_MODE: PCAP;
62   ENABLE_CMD_EXEC;
63   KEY: myencryptkey;
64   FW_ACCESS_TIMEOUT: 30;
65
66 5) This example is identical to example 4) above, but now we specify a
67    regular expression which any remote command must match before being
68    executed:
69
70   SOURCE: ANY;
71   OPEN_PORTS: tcp/22;
72   DATA_COLLECT_MODE: PCAP;
73   ENABLE_CMD_EXEC;
74   CMD_REGEX: /sbin/iptables.*ACCEPT;
75   KEY: myencryptkey;
76   FW_ACCESS_TIMEOUT: 30;
77
78 6) This example is similar to example 1) above, but this time instruct
79    fwknopd to read packets from a file that is written to by a sniffer
80    process or by something like the ulogd pcap writer (use ULOG_PCAP for
81    this).  The specific file path is defined by the PCAP_FILE keyword in
82    /etc/fwknop/fwknop.conf).  We also require that the username on the
83    system that generates the authorization packet is "mbr":
84
85   SOURCE: ANY;
86   OPEN_PORTS: tcp/22;
87   DATA_COLLECT_MODE: FILE_PCAP;
88   KEY: myencryptkey;
89   FW_ACCESS_TIMEOUT: 30;
90   REQUIRE_USERNAME: mbr;