Deprecate -F, --rules-data and --rules-file args

Since we already have a pretty concise rule specification format, there
really is no need to specify YAML or JSON *inline* via the
-F/--rules-data argument, since the -r argument is superior in every
way, given that YAML is whitespace/newline-sensitive.

Another point is that the --rules-file argument always sounded a bit
weird (is it "rules file" or "rule file"?) and just calling it --file is
much less awkward and also unambiguous since all that can be passed via
file are rules, similar to patterns for grep and its -f/--file option.

Right now, the -f/--file option still reads YAML and doesn't yet
recognise a newline separated list of rules. The implementation will be
a little bit trickier, since we want to keep the same command line
argument but allow for both formats to coexist and simply display a
deprecation warning for YAML.

The reason why I decided to remove YAML entirely is because when using
ip2unix in practice, I did not have even *one* occasion where such a
rule file would be helpful and instead just used the -r arguments.

Since the rule file was implemented first, the option names are still
unchanged to date, but when introducing the -r command line option, I
decided to go for shorter names instead.

This however is a bit confusing if you're used to -r and suddenly have
to use entirely different option names for the rule files, so it's just
one additional reason to remove it entirely.

Signed-off-by: aszlig <[email protected]>

Author: aszlig

CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog], and this project adheres to
 [Semantic Versioning].
 
+## [Unreleased]
+
+### Added
+- Deprecation warnings if rules are specified in YAML format.
+
 ## [2.1.3] - 2020-06-01
 
 ### Fixed
@@ -93,6 +98,7 @@ The format is based on [Keep a Changelog], and this project adheres to
 - The initial release, which evolved from an early prototype specific to a
   certain use case into a more generic command line tool.
 
+[Unreleased]: https://github.com/nixcloud/ip2unix/compare/v2.1.3...HEAD
 [2.1.3]: https://github.com/nixcloud/ip2unix/compare/v2.1.2...v2.1.3
 [2.1.2]: https://github.com/nixcloud/ip2unix/compare/v2.1.1...v2.1.2
 [2.1.1]: https://github.com/nixcloud/ip2unix/compare/v2.1.0...v2.1.1

README.adoc

@@ -19,10 +19,8 @@ ip2unix - Turn IP sockets into Unix domain sockets
 
 [verse]
 *ip2unix* [*-v*...] [*-p*] *-f* 'RULES_FILE' 'PROGRAM' ['ARGS'...]
-*ip2unix* [*-v*...] [*-p*] *-F* 'RULES_DATA' 'PROGRAM' ['ARGS'...]
 *ip2unix* [*-v*...] [*-p*] *-r* 'RULE' [*-r* 'RULE']... 'PROGRAM' ['ARGS'...]
 *ip2unix* [*-v*...] [*-p*] *-c* *-f* 'RULES_FILE'
-*ip2unix* [*-v*...] [*-p*] *-c* *-F* 'RULES_DATA'
 *ip2unix* [*-v*...] [*-p*] *-c* *-r* 'RULE' [*-r* 'RULE']...
 *ip2unix* *-h*
 *ip2unix* *--version*
@@ -87,8 +85,8 @@ Executes a program and converts IP to Unix domain sockets at runtime based on a
 list of rules, either given via short command line options (see {rulespec}) or
 via a file with a list of rules (see {rulefileformat}). The first matching rule
 causes *ip2unix* to replace the current IP socket with a Unix domain socket
-based on the options given. For example if a <<rule-socket-path,*socketPath*>>
-is specified, the Unix domain socket will bind or listen to the given path.
+based on the options given. For example if a <<rule-socket-path,*path*>> is
+specified, the Unix domain socket will bind or listen to the file given.
 
 ifndef::manmanual[]
 
@@ -149,6 +147,8 @@ endif::[]
 * https://mesonbuild.com/[Meson], at least version 0.46.0.
 * https://ninja-build.org/[Ninja], at least version 1.5.
 * https://github.com/jbeder/yaml-cpp[yaml-cpp], at least version 0.5.0
+  Requirement will be removed in *ip2unix* version 3, since the YAML rule file
+  format is deprecated.
 * {cpp} compiler supporting {cpp}17 (https://gcc.gnu.org/[GNU G++] version 7.0
   onwards).
 * https://www.python.org/[Python] 3, at least version 3.6 is needed for running
@@ -368,12 +368,9 @@ ifdef::manmanual[]
   A single rule for one particular socket to match, can be used several times
   to specify a set of rules similar to the sequence of the rule file.
 
-*-f, --rules-file*='RULES_FILE'::
-  Specifies a YAML or JSON file consisting of a sequence of rules.
-
-*-F, --rules-data*='RULES_DATA'::
-  Similar to *-f*, but instead of specifying a file, directly pass the contents
-  as an argument.
+*-f, --file*='FILE'::
+  Read rules from 'FILE', which contains a newline-separated list of rules as
+  specified via `-r`.
 
 *-v, --verbose*::
   Increases the level of verbosity, according to the following table:
@@ -403,18 +400,21 @@ just use two consecutive backslashes instead.
 The following flags are available:
 
 *in* | *out*::
-  Corresponds to the <<rule-opt-direction,*direction*>> rule file option and
-  if it is not set, both incoming and outgoing connections are matched.
+  Whether this rule applies to a server-side socket (`in`), a client-side
+  socket (`out`) or both if neither `in` nor `out` is specified.
 
 *tcp* | *udp*::
-  Either match TCP or UDP sockets or both if none of these flags are set
-  (<<rule-opt-type,*type*>> rule file option).
+  Specifies the IP type, which currently is either `tcp` for TCP sockets, `udp`
+  for UDP sockets or if it is not defined it matches both UDP and TCP sockets.
 
 ifndef::without-systemd[]
 *systemd*[='FD_NAME']::
-  Enable systemd socket activation
-  (see <<rule-opt-socket-activation,*socketActivation*>> below), optionally
-  specifying a file descriptior name (<<rule-opt-fdname,*fdName*>>).
+  Use the socket passed along via file descriptor by systemd instead of
+  creating one.
++
+  An optional file descriptor name ('FD_NAME') can be specified to
+  distinguish between several socket units. This corresponds to the {fdname}
+  systemd socket option.
 endif::[]
 
 *reject*[='ERRNO']::
@@ -427,153 +427,48 @@ endif::[]
   without the application noticing.
 
 *ignore*::
-  Don't handle the socket matching this rule, see the corresponding rule file
-  option <<rule-opt-ignore,*ignore>>.
+  Prevents a socket from being converted to a Unix domain socket if this is
+  set. This is useful to exempt specific sockets from being matched when
+  another rule matches a broad scope.
 
 These options are available:
 
 *addr*[*ess*]='ADDRESS'::
-  Optional, specifies an IPv4 or IPv6 address, see
-  <<rule-opt-address,*address*>> rule file option.
+  The IP address to match, which can be either an IPv4 or an IPv6 address.
 
 *port*='PORT'[-'PORT_END']::
-  Optional, specifies a port to match, see the <<rule-opt-port,*port*>> and
-  optionally the <<rule-opt-port-end,*portEnd*>> rule file option if you want
-  to specify a port range.
-
-*path*='SOCKET_PATH'::
-  The path to the socket file to either bind or connect to, which is similar to
-  the <<rule-socket-path,*socketPath*>> rule file option but also allows
-  relative paths.
-
-== Rule file format
-
-The rule file (specified via *-f* is a YAML file (or JSON, as it is a subset of
-YAML), consisting of an array of objects.
-
-Each object consists of keys/values which define which IP sockets to match
-and which Unix domain sockets to assign them to.
-
-=== Rule file options
-
-[[rule-opt-direction]]*direction*::
-
-Whether this rule applies to a server-side socket (`incoming`), a client-side
-socket (`outgoing`) or both if not defined.
-
-[[rule-opt-type]]*type*::
-
-Specifies the IP type, which currently is either `tcp` for TCP sockets, `udp`
-for UDP sockets or if it is not defined it matches both UDP and TCP sockets.
-
-[[rule-opt-address]]*address*::
-
-The IP address to match, which can be either an IPv4 or an IPv6 address.
-
-[[rule-opt-port]]*port*::
-
-UDP or TCP port number (depending on which <<rule-opt-type,*type*>> is set),
-which for outgoing connections specifies the target port and for incomping
-connections the port that the socket is bound to.
-
-[[rule-opt-port-end]]*portEnd*::
-
-Optionally specifies the end of a port range to match, so for example if
-<<rule-opt-port,*port*>> is `2000` and *portEnd* is `3000` all ports in the
-range from 2000 to 3000 (inclusive) are matched.
-
-[[rule-socket-path]]*socketPath*::
+  UDP or TCP port number which for outgoing connections specifies the target
+  port and for incomping connections the port that the socket is bound to.
++
+If a range is specified by separating two port numbers via `-`, the given
+range is matched instead of just a single port. The range is inclusive, so if
+`2000-3000` is specified, both port 2000 and port 3000 are matched as well.
 
-The path to the socket file to use for either binding or connecting to
-depending on whether the above options apply for a particular IP socket.
+[[rule-socket-path]]*path*='SOCKET_PATH'::
+  The path to the socket file to either bind or connect to.
 +
-Placeholders are allowed here and those are substituted accordingly:
+Placeholders are allowed here and are substituted accordingly:
 +
 [horizontal]
 *%p*;; port number
 *%a*;; IP address or `unknown`
 *%t*;; socket type (`tcp`, `udp` or `unknown`)
 *%%*;; verbatim `%`
 
-ifndef::without-systemd[]
-[[rule-opt-socket-activation]]*socketActivation*::
-ifndef::manmanual[]
-If *ip2unix* is compiled with systemd support, whether to use socket activation
-endif::[]
-ifdef::manmanual[]
-Whether to use systemd socket activation
-endif::[]
-instead of a <<rule-socket-path,*socketPath*>>. See {systemd_socket}.
-
-[[rule-opt-fdname]]*fdName*::
-An optional file descriptor name for socket activation which can be used to
-distinguish between several socket units. This corresponds to the {fdname}
-systemd socket option.
-endif::[]
-
-[[rule-reject]]*reject*::
-  If true, reject calls to *connect* and *bind* with `EACCES`.
-
-*rejectError*::
-  Specifies an alternative error code to be returned by
-  <<rule-reject,*reject*>> instead of `EACCES`. This can be either a string
-  such as `EADDRINUSE` (case does not matter) or an integer.
-
-*blackhole*::
-  If true, a temporary file system path is used and unlinked shortly
-  thereafter, so the socket is effectively deactivated in a way that the
-  application should not recognize. Only valid if
-  <<rule-opt-direction,*direction*>> is `incoming`.
-
-[[rule-opt-ignore]]*ignore*::
-  Prevents a socket from being converted to a Unix domain socket if this is
-  true. This is useful to exempt specific sockets from being matched when
-  another rule matches a broad scope.
-
 == Examples
 
 === Simple HTTP client/server
 
-On the server side with the rule file `rules-server.yaml`:
-
-[source,yaml]
----------------------------------------------------------------------
-- direction: incoming
-  socketPath: /tmp/test.socket
----------------------------------------------------------------------
-
 The following command spawns a small test web server listening on
 `/tmp/test.socket`:
 
-[source,sh-session]
----------------------------------------------------------------------
-$ ip2unix -f rules-server.yaml python3 -m http.server 8000
----------------------------------------------------------------------
-
-The same can be achieved using *-r*:
-
 [source,sh-session]
 ---------------------------------------------------------------------
 $ ip2unix -r in,path=/tmp/test.socket python3 -m http.server 8000
 ---------------------------------------------------------------------
 
-On the client side with `rules-client.yaml`:
-
-[source,yaml]
----------------------------------------------------------------------
-- direction: outgoing
-  socketPath: /tmp/test.socket
----------------------------------------------------------------------
-
-This connects to the test server listening on `/tmp/test.socket`
-and should show the directory listing:
-
-[source,sh-session]
----------------------------------------------------------------------
-$ ip2unix -f rules-client.yaml curl http://1.2.3.4/
----------------------------------------------------------------------
-
-With the *-r* option:
+This connects to the above test server listening on `/tmp/test.socket` and
+should show a directory listing:
 
 [source,sh-session]
 ---------------------------------------------------------------------
@@ -582,48 +477,37 @@ $ ip2unix -r out,path=/tmp/test.socket curl http://1.2.3.4/
 
 === More complicated example
 
-[source,yaml]
+For example the following could be put into a file given by the *-f* command
+line argument:
+
 --------------------------------------------
-- direction: outgoing                 ## <1>
-  port: 53
-  ignore: true
-- direction: outgoing                 ## <2>
-  type: tcp
-  socketPath: /run/some.socket
-- direction: incoming                 ## <3>
-  address: 1.2.3.4
-  socketPath: /run/another.socket
-- direction: incoming                 ## <4>
-  port: 80
-  address: abcd::1
-  blackhole: true
-- direction: incoming                 ## <5>
-  port: 80
-  reject: true
-  rejectError: EADDRINUSE
+out,port=53,ignore
+out,tcp,path=/run/some.socket
+in,addr=1.2.3.4,path=/run/another.socket
+in,port=80,address=abcd::1,blackhole
+in,port=80,reject=EADDRINUSE
 ifndef::without-systemd[]
-- direction: incoming                 ## <6>
-  type: tcp
-  port: 22
-  socketActivation: true
-  fdName: ssh
+in,tcp,port=22,systemd=ssh
 endif::without-systemd[]
 --------------------------------------------
 
-<1> All outgoing connections to port 53 (no matter if it's TCP or UDP) will not
-    be converted into Unix domain sockets.
-<2> This rule will redirect all TCP connections except to port 53 (see above)
-    to use the Unix domain socket at `/run/some.socket`.
-<3> Matches the socket that listens to any port on the IPv4 address `1.2.3.4`
-    and instead binds it to the Unix domain socket at `/run/another.socket`.
-<4> The application may bind to the IPv6 address `abcd::1` on port 80 but it
-    will not receive any connections, because no socket path exists.
-<5> Trying to bind to port 80 on addresses other than `abcd::1` will result
-    in an `EADDRINUSE` error.
+Each line corresponds to a single rule, that is processed in order of
+appearance and the above example would result in the following:
+
+. All outgoing connections to port 53 (no matter if it's TCP or UDP) will not
+  be converted into Unix domain sockets.
+. This rule will redirect all TCP connections except to port 53 (see above) to
+  use the Unix domain socket at `/run/some.socket`.
+. Matches the socket that listens to any port on the IPv4 address `1.2.3.4` and
+  instead binds it to the Unix domain socket at `/run/another.socket`.
+. The application may bind to the IPv6 address `abcd::1` on port 80 but it will
+  not receive any connections, because no socket path exists.
+. Trying to bind to port 80 on addresses other than `abcd::1` will result in an
+  `EADDRINUSE` error.
 ifndef::without-systemd[]
-<6> Will prevent the TCP socket that would listen on port 22 to not listen at
-    all and instead use the systemd-provided file descriptor named `ssh` for
-    operations like {syscall_accept}.
+. Will prevent the TCP socket that would listen on port 22 to not listen at all
+  and instead use the systemd-provided file descriptor named `ssh` for
+  operations like {syscall_accept}.
 endif::[]
 
 The same can be achieved solely using *-r* commandline arguments:
@@ -634,6 +518,7 @@ The same can be achieved solely using *-r* commandline arguments:
 $ ip2unix -r out,port=53,ignore \
           -r out,tcp,path=/run/some.socket \
           -r in,addr=1.2.3.4,path=/run/another.socket \
+          -r in,port=80,address=abcd::1,blackhole \
           -r in,port=80,reject=EADDRINUSE {systemd_backslash}
 ifndef::without-systemd[]
           -r in,tcp,port=22,systemd=ssh