4.4.3 Scripts

Apart from reading the server and host configuration files, tinc can also run scripts at certain moments. Below is a list of filenames of scripts and a description of when they are run. A script is only run if it exists and if it is executable.

Scripts are run synchronously; this means that tinc will temporarily stop processing packets until the called script finishes executing. This guarantees that scripts will execute in the exact same order as the events that trigger them. If you need to run commands asynchronously, you have to ensure yourself that they are being run in the background.

Under Windows, the scripts should have the extension .bat or .cmd.

/usr/local/etc/tinc/netname/tinc-up

This is the most important script. If it is present it will be executed right after the tinc daemon has been started and has connected to the virtual network device. It should be used to set up the corresponding network interface, but can also be used to start other things.

Under Windows you can use the Network Connections control panel instead of creating this script.

/usr/local/etc/tinc/netname/tinc-down

This script is started right before the tinc daemon quits.

/usr/local/etc/tinc/netname/hosts/host-up

This script is started when the tinc daemon with name host becomes reachable.

/usr/local/etc/tinc/netname/hosts/host-down

This script is started when the tinc daemon with name host becomes unreachable.

/usr/local/etc/tinc/netname/host-up

This script is started when any host becomes reachable.

/usr/local/etc/tinc/netname/host-down

This script is started when any host becomes unreachable.

/usr/local/etc/tinc/netname/subnet-up

This script is started when a Subnet becomes reachable. The Subnet and the node it belongs to are passed in environment variables.

/usr/local/etc/tinc/netname/subnet-down

This script is started when a Subnet becomes unreachable.

/usr/local/etc/tinc/netname/invitation-created

This script is started when a new invitation has been created.

/usr/local/etc/tinc/netname/invitation-accepted

This script is started when an invitation has been used.

The scripts are started without command line arguments, but can make use of certain environment variables. Under UNIX like operating systems the names of environment variables must be preceded by a $ in scripts. Under Windows, in .bat or .cmd files, they have to be put between % signs.

NETNAME

If a netname was specified, this environment variable contains it.

NAME

Contains the name of this tinc daemon.

DEVICE

Contains the name of the virtual network device that tinc uses.

INTERFACE

Contains the name of the virtual network interface that tinc uses. This should be used for commands like ifconfig.

NODE

When a host becomes (un)reachable, this is set to its name. If a subnet becomes (un)reachable, this is set to the owner of that subnet.

REMOTEADDRESS

When a host becomes (un)reachable, this is set to its real address.

REMOTEPORT

When a host becomes (un)reachable, this is set to the port number it uses for communication with other tinc daemons.

SUBNET

When a subnet becomes (un)reachable, this is set to the subnet.

WEIGHT

When a subnet becomes (un)reachable, this is set to the subnet weight.

INVITATION_FILE

When the invitation-created script is called, this is set to the file where the invitation details will be stored.

INVITATION_URL

When the invitation-created script is called, this is set to the invitation URL that has been created.

Do not forget that under UNIX operating systems, you have to make the scripts executable, using the command chmod a+x script.