JUMPER
NAMESYNOPSIS
DESCRIPTION
OPTIONS
CONFIGURATION
PREPROCESSOR
SIGNALS
EXIT CODE
EXAMPLES
NOTES
DOWNLOADS
SEE ALSO
AUTHORS
BUG REPORTS
COPYRIGHT
NAME
jumper - bring up network links on demand
SYNOPSIS
jumper
[-Edf] [-P FILE] [-l
PRIO] [-D SYMBOL[=VALUE]]
[-I DIR]
[--debug] [--foreground]
[--define=SYMBOL[=VALUE]]
[--include-directory=DIR]
[--no-preprocessor]
[--preprocessor=COMMAND]
[--pidfile=FILE] [CONFIG]
jumper [-HhV] [--help] [--version]
[--config-help]
DESCRIPTION
Jumper monitors network interfaces for certain kinds of traffic and starts preconfigured external programs when such traffic is detected. It is designed mainly to bring up network links (such as VPN and the like) on demand.
The configuration file tells the program on which interfaces to listen, what packets to catch and what program to start when such packets are detected. The default location for the configuration file is /etc/jumper.conf. If the CONFIG argument is supplied, it names the configuration file to be read instead of the default one.
See the section CONFIGURATION, for a detailed description of configuration file syntax.
Unless instructed otherwise, jumper uses m4(1) to preprocess its configuration file. See the section PREPROCESSOR for a detailed discussion.
After successful parsing of the configuration file, the program switches the configured interfaces to promiscuous mode, detaches itself from the controlling terminal and begins listening on the interfaces.
When a packet arrives that matches the specified conditions, jumper checks whether the program configured for this kind of packets is already running. If it is not, it will be started. Thus, for example, the following configuration fragment instructs the program to start openvpn whenever a packet coming to any IP address from the network 10.0.1.0/24 is detected:
listen myvpn {
interface eth1;
match-destination 10.0.1.0/24;
command "/usr/bin/openvpn /etc/openvpn.conf";
}
OPTIONS
-D, --define=SYMBOL[=VALUE]
Define preprocessor symbol.
-E |
Preprocess configuration file and exit. |
-I, --include-directory=DIR
Add DIR to the list of preprocessor include directories.
-P FILE, --pidfile=FILE
Set PID file name.
-d, --debug
Increase debugging level. See the description of debug statement in CONFIGURATION STATEMENTS, for a detailed discussion of debugging levels and their effect on the program output.
-f, --foreground
Remain in foreground.
-l PRIO
When running in the foreground (see the -f option above), log messages with priority PRIO and higher to the stderr, as well as to the syslog. PRIO is one of the usual syslog.conf(8) priorities: debug, info, notice, warning, err, crit, alert, emerg, or none, which suppresses any output to standard error.
By default, all priorities are logged.
--no-preprocessor
Disable preprocessing of the configuration file. Read it verbatim.
--preprocessor=COMMAND
Use COMMAND instead of the default preprocessor.
Informational
options:
-h, --help
Give a concise help summary.
-H, --config-help
Show configuration file summary and exit.
--usage
Print a short usage message.
-V, --version
Print program version.
CONFIGURATION
The configuration file consists of statements and comments.
There are three classes of lexical tokens: keywords, values, and separators. Blanks, tabs, newlines and comments, collectively called white space are ignored except as they serve to separate tokens. Some white space is required to separate otherwise adjacent keywords and values.
Comments
Comments may appear anywhere where white space may appear in
the configuration file. There are two kinds of comments:
single-line and multi-line comments. Single-line comments
start with # or // and continue to the end of
the line:
# This is a
comment
// This too is a comment
Multi-line or C-style comments start with the two characters /* (slash, star) and continue until the first occurrence of */ (star, slash).
Multi-line comments cannot be nested. However, single-line comments may well appear within multi-line ones.
Pragmatic
Comments
Pragmatic comments are similar to the usual single-line
comments, except that they cause some changes in the way the
configuration is parsed. Pragmatic comments begin with a
# sign and end with the next physical newline
character.
#include <FILE>
#include FILE
Include the contents of the file file. Both forms are equivalent. The FILE must be an absolute file name.
#include_once
<FILE>
#include_once FILE
Same as #include, except that, if the FILE has already been included, it will not be included again.
#line num
#line num
"FILE"
This line causes the parser to believe, for purposes of error diagnostics, that the line number of the next source line is given by num and the current input file is named by FILE. If the latter is absent, the remembered file name does not change.
# num "FILE"
This is a special form of the #line statement, understood for compatibility with the C preprocessor.
Simple
statement
A simple statement consists of a keyword and value
separated by any amount of whitespace. Simple statement is
terminated with a semicolon (;).
The following is a simple statement:
pidfile /var/run/jumper.pid;
A value can be one of the following:
number |
A number is a sequence of decimal digits. |
boolean
One of: yes, true, t or 1, meaning true, and no, false, nil, 0 meaning false.
unquoted string
Any sequence of letters, digits, and any of the following characters: _, -, ., /, @, *, : is treated as a string.
quoted string
Any sequence of characters enclosed in double-quotes ("). A backslash appearing within a quoted string introduces an escape sequence, which is replaced with a single character according to the following rules:
Sequence Expansion ASCII
\\ |
|||
\ |
134 | ||
\" |
|||
" |
042 | ||
\a |
|||
audible bell |
007 | ||
\b |
|||
backspace |
010 | ||
\f |
|||
form-feed |
014 | ||
\n |
|||
new line |
012 | ||
\r |
|||
charriage return |
015 | ||
\t |
|||
horizontal tabulation |
011 | ||
\v |
|||
vertical tabulation |
013 |
In addition, the sequence \newline is removed from the string. This allows to split long strings over several physical lines, e.g.:
"a long
string may be\
split over several lines"
If the character following a backslash is not one of those specified above, the backslash is ignored and a warning is issued.
Two or more adjacent quoted strings are concatenated, which gives another way to split long strings over several lines to improve readability. The following fragment produces the same result as the example above:
"a long
string may be"
" split over several lines"
Here-document
A here-document is a special construct that allows to introduce strings of text containing embedded newlines.
The <<word construct instructs the parser to read all the following lines up to the line containing only word, with possible trailing blanks. Any lines thus read are concatenated together into a single string. For example:
<<EOT
A multiline
string
EOT
The body of a here-document is interpreted the same way as a double-quoted string, unless word is preceded by a backslash (e.g. <<\EOT) or enclosed in double-quotes, in which case the text is read as is, without interpretation of escape sequences.
If word is prefixed with - (a dash), then all leading tab characters are stripped from input lines and the line containing word. Furthermore, - is followed by a single space, all leading whitespace is stripped from them. This allows to indent here-documents in a natural fashion. For example:
<<- TEXT
The leading whitespace will be
ignored when reading these lines.
TEXT
It is important that the terminating delimiter be the only token on its line. The only exception to this rule is allowed if a here-document appears as the last element of a statement. In this case a semicolon can be placed on the same line with its terminating delimiter, as in:
help-text
<<-EOT
A sample help text.
EOT;
list |
A comma-separated list of values, enclosed in parentheses. The following example shows a statement whose value is a list of strings: |
option (wait, stderr);
In any context where a list is appropriate, a single value is allowed without being a member of a list: it is equivalent to a list with a single member. This means that, e.g.
option stderr;
is equivalent to
option (stderr);
Block
Statement
A block statement introduces a logical group of statements.
It consists of a keyword, optionally followed by a value,
called a tag, and a sequence of statements enclosed
in curly braces, as shown in the example below:
listen vpn {
interface eth0;
match-destination 10.0.0.0/8;
command "openvpn";
}
The closing curly brace may be followed by a semicolon, although this is not required.
MACRO
EXPANSION
Arguments to certain statements undergo macro expansion
before further use. During the macro expansion any
occurrence of ${NAME} is replaced with the value of
macro NAME. Macro names follow the usual convention:
they begin with a letter and contain letters, digits and
underscores. Curly braces around the NAME are
optional. They are required only if the macro reference is
followed by a character that is not to be interpreted as
part of its name, as in ${command}string.
The sets of macro names available for expansion differs depending on the configuration context and are discussed in detail below.
CONFIGURATION
STATEMENTS
foreground BOOL;
If BOOL is true, do not detach from the controlling terminal.
pidfile FILE;
After successful startup, write the PID of the running process to FILE. The file will be removed before normal termination. The default FILE is /usr/var/run/jumper.pid.
debug NUMBER;
Set debugging level. Implemented levels are:
0 |
No debugging info. | ||
1 |
Additional information regarding process management. | ||
2 |
Log information about I/O redirection processes. | ||
3 |
Log captured IP packets. |
shutdown-timeout NUMBER;
When jumper is terminated, it shuts down all subprocesses launched so far. This statement sets the time to wait for them to exit properly. If any processes are left after NUMBER of seconds, jumper will terminate them forcefully, delivering them the SIGKILL signal. The default timeout is 15 seconds.
listen NAME { ... }
Define a listener. The NAME is a unique string identifying this listener in the configuration. The following instructions are available for use in the { ... } block:
interface IFACE;
Listen on the specified interface. This statement is mandatory.
match-source CIDR-LIST;
Match only packets coming from one of the listed networks.
match-destination CIDR-LIST;
Match only packets going to one of the listed networks. This statement must be present.
If both match-source and match-destination are supplied, their conditions are joined by logical AND.
command COMMAND-LINE;
Run COMMAND-LINE if the
conditions are satisfied. The argument is parsed using the
same algorithm as used by the shell. It is subject to macro
expansion. The following macro names are defined:
program
The program name (jumper).
file |
Name of the configuration file where the command statement is located. | ||
line |
Line number in that file. | ||
src |
Source IP address. | ||
dst |
Destination IP address. |
option OPTION-LIST;
A list of additional options. Currently the following options are defined:
stdout |
Capture the standard output of the command and redirect it to the syslog with the LOG_INFO priority. | ||
stderr |
Capture the standard error of the command and redirect it to the syslog with the LOG_ERR priority. | ||
nullin |
Do not close standard input. Redirect it from /dev/null instead. Use this option with commands that require their standard input to be open (e.g. pppd nodetach). |
environ ENV-SPEC;
Modify command environment. By default the command inherits the environment of jumper augmented with the following variables:
JUMPER |
Name of the program. |
JUMPER_VERSION
Program version.
JUMPER_LOCUS
Location in the configuration file which caused execution of the command (file name and line number separated with a colon).
JUMPER_EVENT
Name of the event that triggered the action; one of: startup, cleanup, exit, or signal.
The environ statement allows for trimming the environment. Its argument is a list of one or more of the following environment modification directives. Before applying, the argument undergoes macro expansion using the same set of macros as the command statement (which see).
- (a single dash)
Clear the inherited environment, but retain the variables added by jumper. The removed environment variables can be selectively restored by the directives that follow. This must be the first directive in the list.
-- (double-dash)
Clear the entire environment, including the variables added by jumper. This must be the first directive in the list.
-NAME |
Unset the variable NAME. |
-NAME=VAL
Unset the environment variable NAME only if its value is VAL.
NAME |
Restore the environment variable NAME. This directive is useful after - or -- to retain some variables from the environment. |
NAME=VALUE
Define environment variable NAME to the VALUE. VALUE can contain macro variables, which will be expanded prior to the assignment.
NAME+=VALUE
Retain the variable NAME and append VALUE to its existing value. If no such variable is present in the environment, it will be created and assigned the VALUE. If VALUE begins with a punctuation character, this character is removed from it before the assignment. This is convenient for using this construct with environment variables like PATH, e.g.:
PATH+=:/sbin
In this example, if PATH exists, :/sbin will be appended to it. Otherwise, it will be created and assigned the value /sbin.
The VALUE can contain macro variables, which will be expanded prior to the assignment.
NAME=+VALUE
Retain the variable NAME and prepend VALUE to its existing value. If no such variable is present in the environment, it will be created and assigned the VALUE. In this case, if VALUE ends with a punctuation character, this character will be removed from it before the assignment.
The VALUE can contain macro variables, which will be expanded prior to the assignment.
onevent EVLIST { ... };
This block statement instructs jumper to perform a specified action when an event listed in EVLIST is detected. EVLIST can be either a single event, or a whitespace separated list of events, or a comma-separated list of events in parentheses. Valid events are:
STARTUP
The action is run immediately after jumper starts up, before it begins listening on interfaces. It can be used to set up firewall rules, etc.
CLEANUP
The action is run before jumper terminates, right after termination of all commands.
Decimal number in range 0..127
The action is performed when the command terminates with the given code.
EX+N |
The action is performed when the command terminates with the code N. |
Symbolic name of exit code from sysexits.h
The action is performed when the command terminates with the given exit code. Currently the following symbolic names are used: EX_OK (0), EX_USAGE (64), EX_DATAERR (65), EX_NOINPUT (66), EX_NOUSER (67), EX_NOHOST (68), EX_UNAVAILABLE (69), EX_SOFTWARE (70), EX_OSERR (71), EX_OSFILE (72), EX_CANTCREAT (73), EX_IOERR (74), EX_TEMPFAIL (75), EX_PROTOCOL (76), EX_NOPERM (77), and EX_CONFIG (78).
SIG+N |
The action is performed when the command terminates on signal N (decimal number) |
Symbolic signal name as defined in signal.h
The action is performed when the command terminates on this signal.
The following
statements can be used within the block:
command COMMAND-LINE;
Run COMMAND-LINE. The
following macros are expanded in the argument prior to
execution:
program
The program name (jumper).
file |
Name of the configuration file where the command statement is located. | ||
line |
Line number in that file. | ||
event |
Name of the event that triggered the action; one of: startup, cleanup, exit, or signal. | ||
status |
Program termination status as returned by the waitpid(2) call. |
exitcode
Exit code returned by the program, or the number of the signal that caused its termination.
environ ENV-SPEC;
Modify command environment. See the description of the environ statement above, for a detailed discussion.
timeout NUMBER
If the command does not exit within NUMBER seconds from its start, terminate it forcefully. The default is 5 seconds.
PREPROCESSOR
Prior to parsing, the configuration file is preprocessed using m4(1).
The include path is set initially to the following two directories:
/usr/share/jumper/1.2/include
/usr/share/jumper/include
It can be further modified using the -I (--include-directory) command line option.
If the file pp-setup is found in the include path, it is sourced before the configuration file. This can be used to provide macros and constants for the configuration.
Additional definitions can also be provided from the command line using the -D (--define) option.
To view preprocessed configuration, use the -E option. It prints the preprocessed text on the standard output.
To disable preprocessing, use the --no-preprocessor option.
SIGNALS
Delivering the SIGHUP signal causes jumper to re-read its configuration file. When doing so, it will not touch any running processes started on behalf of listeners that underwent no changes, compared to the previous configuration. However, any command which was started for a listener whose configuration did change will be terminated prior to updating configuration.
If any errors are detected in the configuration file, the current configuration will remain unchanged.
The SIGALRM and SIGCHLD signals are used internally.
The following signals cause normal program termination: SIGTERM, SIGQUIT, SIGINT.
The signals SIGUSR1 and SIGUSR2 are reserved for future use.
EXIT CODE
0 |
Successful termination. | ||
64 |
Command line usage error. | ||
70 |
Internal software error (unknown data link or the like). | ||
71 |
System error (can’t fork, out of memory, etc.) | ||
78 |
Configuration error. |
EXAMPLES
Run openvpn whenever a packet directed to one of the addresses from the 10.0.0.0/8 network is detected on the interface eth1. Redirect both its standard error and standard output to syslog:
listen vpn {
interface eth0;
match-destination (10.0.0.0/8); | |
command "/usr/sbin/openvpn /etc/openvpn.conf"; | |
option (stderr, stdout); |
}
NOTES
When using jumper to start VPN, the usual operation sequence is as follows:
1. |
A client initiates connection to an IP address that should be provided by the VPN which is currently not active. | ||
2. |
Jumper detects packets destined to that address and launches external program that brings the VPN up. | ||
3. |
Once the VPN is up, the client successfully connects to the required IP. |
To make this possible the following provisions should be made:
1. |
The iptables(8) FORWARD chain must initially contain a statement preventing packets for the IP addresses covered by the VPN from reaching their destination, e.g.: |
-A FORWARD -d 172.16.0.0/12 -j DROP
2. |
Upon successful startup, the VPN handler must insert to this chain a rule allowing connections to that particular range of addresses. This rule must, of course, be inserted before the DROP rule. As a result, the FORWARD chain will contain something similar to: |
-A FORWARD -d
172.16.0.0/12 -j ACCEPT
-A FORWARD -d 172.16.0.0/12 -j DROP
Exact ways of achieving this depend on the program used to establish VPN connection. For openvpn(8), use the --client-connect option. For vpnc(8), modify the handling of reason=connect in the /etc/vpnc/vpnc-script file.
3. |
Upon VPN termination, that additional rule must be removed. For openvpn(8), use the --client-disconnect option. For vpnc(8), modify the handling of reason=disconnect in the /etc/vpnc/vpnc-script file. |
Notice also, that you might have to specify additional onevent rules to clean-up the firewall table in case of the hang-up or similar conditions. For example, vpnc(8) fails to invoke the /etc/vpnc/vpnc-script if the connection is terminated by the server. In that case it exits with code 1. If you modify the script so that it handles reason=cleanup to clean up the firewall rules, add the following to the listen statement:
onevent 1 {
command "/etc/vpnc/vpnc-script"; |
environ
"reason=cleanup";
}
DOWNLOADS
Jumper is available for download from this location.
The latest version is jumper-1.2.
Recent news, changes and bugfixes can be tracked from the project's development page.
SEE ALSO
AUTHORS
Sergey Poznyakoff
BUG REPORTS
Report bugs to <bug-jumper@gnu.org.ua>.
COPYRIGHT
Copyright
© 2013-2018 Sergey Poznyakoff
License GPLv3+: GNU GPL version 3 or later
<http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and
redistribute it. There is NO WARRANTY, to the extent
permitted by law.
Manpage server at man.gnu.org.ua.
Powered by mansrv 1.1