Add stricter checks for netnames.

[tinc] / doc / tinc.8.in

diff --git a/doc/tinc.8.in b/doc/tinc.8.in
index 2cff94c..6644add 100644 (file)
--- a/doc/tinc.8.in
+++ b/doc/tinc.8.in
@@ -1,4 +1,4 @@
-.Dd 2013-01-15
+.Dd 2014-01-16

 .Dt TINCCTL 8
 .\" Manual page created by:
 .\" Scott Lamb
 .Dt TINCCTL 8
 .\" Manual page created by:
 .\" Scott Lamb


@@ -11,16 +11,39 @@
 .Op Fl -config Ns = Ns Ar DIR
 .Op Fl -net Ns = Ns Ar NETNAME
 .Op Fl -pidfile Ns = Ns Ar FILENAME
 .Op Fl -config Ns = Ns Ar DIR
 .Op Fl -net Ns = Ns Ar NETNAME
 .Op Fl -pidfile Ns = Ns Ar FILENAME

+.Op Fl -force

 .Op Fl -help
 .Op Fl -version
 .Op Fl -help
 .Op Fl -version

-.Ar COMMAND
+.Op Ar COMMAND

 .Sh DESCRIPTION
 This is the control program of tinc, a secure virtual private network (VPN)
 project.
 .Nm
 .Sh DESCRIPTION
 This is the control program of tinc, a secure virtual private network (VPN)
 project.
 .Nm

-communicates with
-.Xr tincd 8
-to alter and inspect the running VPN's state.
+can start and stop
+.Xr tincd 8 ,
+and can to alter and inspect the state of a running VPN.
+It can also be used to change the configuration,
+or to import or export host configuration files from other nodes.
+
+If
+.Nm
+is started with a
+.Ar COMMAND ,
+this command is immediately executed, after which
+.Nm
+exits.
+If no
+.Ar COMMAND
+is given,
+.Nm
+will act as a shell;
+it will display a prompt, and commands can be entered on the prompt.
+If
+.Nm
+is compiled with libreadline, history and command completion are available on the prompt.
+One can also pipe a script containing commands through
+.Nm .
+In that case, lines starting with a # symbol will be ignored.

 .Sh OPTIONS
 .Bl -tag -width indent
 .It Fl n, -net Ns = Ns Ar NETNAME
 .Sh OPTIONS
 .Bl -tag -width indent
 .It Fl n, -net Ns = Ns Ar NETNAME


@@ -32,6 +55,8 @@ Use the cookie from
 to authenticate with a running tinc daemon.
 If unspecified, the default is
 .Pa @localstatedir@/run/tinc. Ns Ar NETNAME Ns Pa .pid.
 to authenticate with a running tinc daemon.
 If unspecified, the default is
 .Pa @localstatedir@/run/tinc. Ns Ar NETNAME Ns Pa .pid.

+.It Fl -force
+Force some commands to work despite warnings.

 .It Fl -help
 Display short list of options.
 .It Fl -version
 .It Fl -help
 Display short list of options.
 .It Fl -version


@@ -47,7 +72,7 @@ option, the value of this environment variable is used.
 .Sh COMMANDS
 .Bl -tag -width indent
 .It init Op Ar name
 .Sh COMMANDS
 .Bl -tag -width indent
 .It init Op Ar name

-Create initial configuration files and RSA and ECDSA keypairs with default length.
+Create initial configuration files and RSA and Ed25519 keypairs with default length.

 If no
 .Ar name
 for this node is given, it will be asked for.
 If no
 .Ar name
 for this node is given, it will be asked for.


@@ -66,6 +91,7 @@ To set a variable for a specific host, use the notation
 .Ar host Ns Li . Ns Ar variable .
 .It add Ar variable Ar value
 As above, but without removing any previously existing configuration variables.
 .Ar host Ns Li . Ns Ar variable .
 .It add Ar variable Ar value
 As above, but without removing any previously existing configuration variables.

+If the variable already exists with the given value, nothing happens.

 .It del Ar variable Op Ar value
 Remove configuration variables with the same name and
 .Ar value .
 .It del Ar variable Op Ar value
 Remove configuration variables with the same name and
 .Ar value .


@@ -79,16 +105,16 @@ You do not need to specify the full path to the file.
 Export the host configuration file of the local node to standard output.
 .It export-all
 Export all host configuration files to standard output.
 Export the host configuration file of the local node to standard output.
 .It export-all
 Export all host configuration files to standard output.

-.It import Op Fl -force
+.It import

 Import host configuration data generated by the
 .Nm
 export command from standard input.
 Already existing host configuration files are not overwritten unless the option
 .Fl -force
 is used.
 Import host configuration data generated by the
 .Nm
 export command from standard input.
 Already existing host configuration files are not overwritten unless the option
 .Fl -force
 is used.

-.It exchange Op Fl -force
+.It exchange

 The same as export followed by import.
 The same as export followed by import.

-.It exchange-all Op Fl -force
+.It exchange-all

 The same as export-all followed by import.
 .It invite Ar name
 Prepares an invitation for a new node with the given
 The same as export-all followed by import.
 .It invite Ar name
 Prepares an invitation for a new node with the given


@@ -106,9 +132,10 @@ optionally with the given extra options.
 .It stop
 Stop
 .Xr tincd 8 .
 .It stop
 Stop
 .Xr tincd 8 .

-.It restart
+.It restart Op tincd options

 Restart
 Restart

-.Xr tincd 8 .
+.Xr tincd 8 ,
+optionally with the given extra options.

 .It reload
 Partially rereads configuration files. Connections to hosts whose host
 config files are removed are closed. New outgoing connections specified
 .It reload
 Partially rereads configuration files. Connections to hosts whose host
 config files are removed are closed. New outgoing connections specified


@@ -119,9 +146,9 @@ will be made.
 Shows the PID of the currently running
 .Xr tincd 8 .
 .It generate-keys Op bits
 Shows the PID of the currently running
 .Xr tincd 8 .
 .It generate-keys Op bits

-Generate both RSA and ECDSA keypairs (see below) and exit.
-.It generate-ecdsa-keys
-Generate public/private ECDSA keypair and exit.
+Generate both RSA and Ed25519 keypairs (see below) and exit.
+.It generate-ed25519-keys
+Generate public/private Ed25519 keypair and exit.

 .It generate-rsa-keys Op bits
 Generate public/private RSA keypair and exit.
 If
 .It generate-rsa-keys Op bits
 Generate public/private RSA keypair and exit.
 If


@@ -145,6 +172,9 @@ format.
 Nodes are colored according to their reachability:
 red nodes are unreachable, orange nodes are indirectly reachable, green nodes are directly reachable.
 Black nodes are either directly or indirectly reachable, but direct reachability has not been tried yet.
 Nodes are colored according to their reachability:
 red nodes are unreachable, orange nodes are indirectly reachable, green nodes are directly reachable.
 Black nodes are either directly or indirectly reachable, but direct reachability has not been tried yet.

+.It dump invitations
+Dump a list of outstanding invitations.
+The filename of the invitation, as well as the name of the node that is being invited is shown for each invitation.

 .It info Ar node | subnet | address
 Show information about a particular node, subnet or address.
 If an address is given, any matching subnet will be shown.
 .It info Ar node | subnet | address
 Show information about a particular node, subnet or address.
 If an address is given, any matching subnet will be shown.


@@ -187,6 +217,43 @@ format to standard output,
 from where it can be redirected to a file or piped through a program that can parse it directly,
 such as
 .Xr tcpdump 8 .
 from where it can be redirected to a file or piped through a program that can parse it directly,
 such as
 .Xr tcpdump 8 .

+.It network Op Ar netname
+If
+.Ar netname
+is given, switch to that network.
+Otherwise, display a list of all networks for which configuration files exist.
+.It fsck
+This will check the configuration files for possible problems,
+such as unsafe file permissions, missing executable bit on script,
+unknown and obsolete configuration variables, wrong public and/or private keys, and so on.
+.Pp
+When problems are found, this will be printed on a line with WARNING or ERROR in front of it.
+Most problems must be corrected by the user itself, however in some cases (like file permissions and missing public keys),
+tinc will ask if it should fix the problem.
+.It sign Op Ar filename
+Sign a file with the local node's private key.
+If no
+.Ar filename
+is given, the file is read from standard input.
+The signed file is written to standard output.
+.It verify Ar name Op Ar filename
+Check the signature of a file against a node's public key.
+The
+.Ar name
+of the node must be given,
+or can be
+.Li .
+to check against the local node's public key, or
+.Li *
+to allow a signature from any node whose public key is known.
+If no
+.Ar filename
+is given, the file is read from standard input.
+If the verification is succesful,
+a copy of the input with the signature removed is written to standard output,
+and the exit code will be zero.
+If the verification failed,
+nothing will be written to standard output, and the exit code will be non-zero.

 .El
 .Sh EXAMPLES
 Examples of some commands:
 .El
 .Sh EXAMPLES
 Examples of some commands:


@@ -196,7 +263,7 @@ tinc -n vpn pcap | tcpdump -r -
 tinc -n vpn top
 .Pp
 .Ed
 tinc -n vpn top
 .Pp
 .Ed

-Example of configuring tinc using
+Examples of changing the configuration using

 .Nm :
 .Bd -literal -offset indent
 tinc -n vpn init foo
 .Nm :
 .Bd -literal -offset indent
 tinc -n vpn init foo