342 lines
10 KiB
Groff
342 lines
10 KiB
Groff
.Dd 2014-01-16
|
|
.Dt TINCCTL 8
|
|
.\" Manual page created by:
|
|
.\" Scott Lamb
|
|
.Sh NAME
|
|
.Nm tinc
|
|
.Nd tinc VPN control
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl cn
|
|
.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 Ar COMMAND
|
|
.Sh DESCRIPTION
|
|
This is the control program of tinc, a secure virtual private network (VPN)
|
|
project.
|
|
.Nm
|
|
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
|
|
Communicate with tincd(8) connected with
|
|
.Ar NETNAME .
|
|
.It Fl -pidfile Ns = Ns Ar FILENAME
|
|
Use the cookie from
|
|
.Ar FILENAME
|
|
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
|
|
Output version information and exit.
|
|
.El
|
|
.Sh ENVIRONMENT VARIABLES
|
|
.Bl -tag -width indent
|
|
.It Ev NETNAME
|
|
If no netname is specified on the command line with the
|
|
.Fl n
|
|
option, the value of this environment variable is used.
|
|
.El
|
|
.Sh COMMANDS
|
|
.Bl -tag -width indent
|
|
.It init Op Ar name
|
|
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.
|
|
.It get Ar variable
|
|
Print the current value of configuration variable
|
|
.Ar variable .
|
|
If more than one variable with the same name exists,
|
|
the value of each of them will be printed on a separate line.
|
|
.It set Ar variable Ar value
|
|
Set configuration variable
|
|
.Ar variable
|
|
to the given
|
|
.Ar value .
|
|
All previously existing configuration variables with the same name are removed.
|
|
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.
|
|
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 .
|
|
If no
|
|
.Ar value
|
|
is given, all configuration variables with the same name will be removed.
|
|
.It edit Ar filename
|
|
Start an editor for the given configuration file.
|
|
You do not need to specify the full path to the file.
|
|
.It export
|
|
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
|
|
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
|
|
The same as export followed by import.
|
|
.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
|
|
.Ar name ,
|
|
and prints a short invitation URL that can be used with the join command.
|
|
.It join Op Ar URL
|
|
Join an existing VPN using an invitation URL created using the invite command.
|
|
If no
|
|
.Ar URL
|
|
is given, it will be read from standard input.
|
|
.It start Op tincd options
|
|
Start
|
|
.Xr tincd 8 ,
|
|
optionally with the given extra options.
|
|
.It stop
|
|
Stop
|
|
.Xr tincd 8 .
|
|
.It restart Op tincd options
|
|
Restart
|
|
.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
|
|
in
|
|
.Xr tinc.conf 5
|
|
will be made.
|
|
.It pid
|
|
Shows the PID of the currently running
|
|
.Xr tincd 8 .
|
|
.It generate-keys Op bits
|
|
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
|
|
.Ar bits
|
|
is omitted, the default length will be 2048 bits.
|
|
When saving keys to existing files, tinc will not delete the old keys;
|
|
you have to remove them manually.
|
|
.It dump [reachable] nodes
|
|
Dump a list of all known nodes in the VPN.
|
|
If the keyword reachable is used, only lists reachable nodes.
|
|
.It dump edges
|
|
Dump a list of all known connections in the VPN.
|
|
.It dump subnets
|
|
Dump a list of all known subnets in the VPN.
|
|
.It dump connections
|
|
Dump a list of all meta connections with ourself.
|
|
.It dump graph | digraph
|
|
Dump a graph of the VPN in
|
|
.Xr dotty 1
|
|
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.
|
|
.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 purge
|
|
Purges all information remembered about unreachable nodes.
|
|
.It debug Ar N
|
|
Sets debug level to
|
|
.Ar N .
|
|
.It log Op Ar N
|
|
Capture log messages from a running tinc daemon.
|
|
An optional debug level can be given that will be applied only for log messages sent to
|
|
.Nm tinc .
|
|
.It retry
|
|
Forces
|
|
.Xr tincd 8
|
|
to try to connect to all uplinks immediately.
|
|
Usually
|
|
.Xr tincd 8
|
|
attempts to do this itself,
|
|
but increases the time it waits between the attempts each time it failed,
|
|
and if
|
|
.Xr tincd 8
|
|
didn't succeed to connect to an uplink the first time after it started,
|
|
it defaults to the maximum time of 15 minutes.
|
|
.It disconnect Ar NODE
|
|
Closes the meta connection with the given
|
|
.Ar NODE .
|
|
.It top
|
|
If
|
|
.Nm
|
|
is compiled with libcurses support, this will display live traffic statistics
|
|
for all the known nodes, similar to the UNIX
|
|
.Xr top 1
|
|
command.
|
|
See below for more information.
|
|
.It pcap
|
|
Dump VPN traffic going through the local tinc node in
|
|
.Xr pcap-savefile 5
|
|
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 .
|
|
.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:
|
|
.Bd -literal -offset indent
|
|
tinc -n vpn dump graph | circo -Txlib
|
|
tinc -n vpn pcap | tcpdump -r -
|
|
tinc -n vpn top
|
|
.Pp
|
|
.Ed
|
|
Examples of changing the configuration using
|
|
.Nm :
|
|
.Bd -literal -offset indent
|
|
tinc -n vpn init foo
|
|
tinc -n vpn add Subnet 192.168.1.0/24
|
|
tinc -n vpn add bar.Address bar.example.com
|
|
tinc -n vpn add ConnectTo bar
|
|
tinc -n vpn export | gpg --clearsign | mail -s "My config" vpnmaster@example.com
|
|
.Ed
|
|
.Sh TOP
|
|
The top command connects to a running tinc daemon and repeatedly queries its per-node traffic counters.
|
|
It displays a list of all the known nodes in the left-most column,
|
|
and the amount of bytes and packets read from and sent to each node in the other columns.
|
|
By default, the information is updated every second.
|
|
The behaviour of the top command can be changed using the following keys:
|
|
.Bl -tag
|
|
.It Ic s
|
|
Change the interval between updates.
|
|
After pressing the
|
|
.Ic s
|
|
key, enter the desired interval in seconds, followed by enter.
|
|
Fractional seconds are honored.
|
|
Intervals lower than 0.1 seconds are not allowed.
|
|
.It Ic c
|
|
Toggle between displaying current traffic rates (in packets and bytes per second)
|
|
and cumulative traffic (total packets and bytes since the tinc daemon started).
|
|
.It Ic n
|
|
Sort the list of nodes by name.
|
|
.It Ic i
|
|
Sort the list of nodes by incoming amount of bytes.
|
|
.It Ic I
|
|
Sort the list of nodes by incoming amount of packets.
|
|
.It Ic o
|
|
Sort the list of nodes by outgoing amount of bytes.
|
|
.It Ic O
|
|
Sort the list of nodes by outgoing amount of packets.
|
|
.It Ic t
|
|
Sort the list of nodes by sum of incoming and outgoing amount of bytes.
|
|
.It Ic T
|
|
Sort the list of nodes by sum of incoming and outgoing amount of packets.
|
|
.It Ic b
|
|
Show amount of traffic in bytes.
|
|
.It Ic k
|
|
Show amount of traffic in kilobytes.
|
|
.It Ic M
|
|
Show amount of traffic in megabytes.
|
|
.It Ic G
|
|
Show amount of traffic in gigabytes.
|
|
.It Ic q
|
|
Quit.
|
|
.El
|
|
.Sh BUGS
|
|
If you find any bugs, report them to tinc@tinc-vpn.org.
|
|
.Sh SEE ALSO
|
|
.Xr tincd 8 ,
|
|
.Xr tinc.conf 5 ,
|
|
.Xr dotty 1 ,
|
|
.Xr pcap-savefile 5 ,
|
|
.Xr tcpdump 8 ,
|
|
.Xr top 1 ,
|
|
.Pa http://www.tinc-vpn.org/ ,
|
|
.Pa http://www.cabal.org/ .
|
|
.Pp
|
|
The full documentation for tinc is maintained as a Texinfo manual.
|
|
If the info and tinc programs are properly installed at your site,
|
|
the command
|
|
.Ic info tinc
|
|
should give you access to the complete manual.
|
|
.Pp
|
|
tinc comes with ABSOLUTELY NO WARRANTY.
|
|
This is free software, and you are welcome to redistribute it under certain conditions;
|
|
see the file COPYING for details.
|
|
.Sh AUTHORS
|
|
.An "Ivo Timmermans"
|
|
.An "Guus Sliepen" Aq guus@tinc-vpn.org
|
|
.Pp
|
|
And thanks to many others for their contributions to tinc!
|