1.\" $FreeBSD: src/usr.sbin/pppctl/pppctl.8,v 1.12.2.8 2003/03/11 22:31:30 trhodes Exp $ 2.\" $DragonFly: src/usr.sbin/pppctl/pppctl.8,v 1.4 2007/11/22 21:17:55 swildner Exp $ 3.Dd June 26, 1997 4.Os 5.Dt PPPCTL 8 6.Sh NAME 7.Nm pppctl 8.Nd PPP control program 9.Sh SYNOPSIS 10.Nm 11.Op Fl v 12.Op Fl t Ar n 13.Op Fl p Ar passwd 14.Xo Oo Ar host : Oc Ns 15.Ar Port | LocalSocket 16.Xc 17.Oo 18.Sm off 19.Ar command Oo ; Ar command Oc Ar ... 20.Sm on 21.Oc 22.Sh DESCRIPTION 23This utility provides command line control of the 24.Xr ppp 8 25daemon. Its primary use is to facilitate simple scripts that 26control a running daemon. 27.Pp 28The 29.Nm 30utility is passed at least one argument, specifying the socket on which 31.Nm ppp 32is listening. Refer to the 33.Sq set server 34command of 35.Nm ppp 36for details. If the socket contains a leading '/', it 37is taken as an 38.Dv AF_LOCAL 39socket. If it contains a colon, it is treated as a 40.Ar host : Ns Ar port 41pair, otherwise it is treated as a TCP port specification on the 42local machine (127.0.0.1). Both the 43.Ar host 44and 45.Ar port 46may be specified numerically if you wish to avoid a DNS lookup 47or don't have an entry for the given port in 48.Pa /etc/services . 49.Pp 50All remaining arguments are concatenated to form the 51.Ar command Ns (s) 52that will be sent to the 53.Nm ppp 54daemon. If any semi-colon characters are found, they are treated as 55.Ar command 56delimiters, allowing more than one 57.Ar command 58in a given 59.Sq session . 60For example: 61.Bd -literal -offset indent 62pppctl 3000 set timeout 300\\; show timeout 63.Ed 64.Pp 65Don't forget to escape or quote the ';' as it is a special character 66for most shells. 67.Pp 68If no 69.Ar command 70arguments are given, 71.Nm 72enters interactive mode, where commands are read from standard input. 73When reading commands, the 74.Xr editline 3 75library is used, allowing command-line editing (with 76.Xr editrc 5 77defining editing behaviour). The history size 78defaults to 79.Em 20 lines . 80.Pp 81The following command line options are available: 82.Bl -tag -width Ds 83.It Fl v 84Display all data sent to and received from the 85.Nm ppp 86daemon. Normally, 87.Nm 88displays only non-prompt lines received. This option is ignored in 89interactive mode. 90.It Fl t Ar n 91Use a timeout of 92.Ar n 93instead of the default 2 seconds when connecting. This may be required 94if you wish to control a daemon over a slow (or even a dialup) link. 95.It Fl p Ar passwd 96Specify the password required by the 97.Nm ppp 98daemon. If this switch is not used, 99.Nm 100will prompt for a password once it has successfully connected to 101.Nm ppp . 102.El 103.Sh ENVIRONMENT 104The following environment variables are understood by 105.Nm 106when in interactive mode: 107.Bl -tag -width XXXXXXXXXX 108.It Ev EL_SIZE 109The number of history lines. The default is 20. 110.It Ev EL_EDITOR 111The edit mode. Only values of "emacs" and "vi" are accepted. Other values 112are silently ignored. This environment variable will override the 113.Ar bind -v 114and 115.Ar bind -e 116commands in 117.Pa ~/.editrc . 118.El 119.Sh EXAMPLES 120If you run 121.Nm ppp 122in 123.Fl auto 124mode, 125.Nm 126can be used to automate many frequent tasks (you can actually control 127.Nm ppp 128in any mode except interactive mode). Use of the 129.Fl p 130option is discouraged (even in scripts that aren't readable by others) 131as a 132.Xr ps 1 133listing may reveal your secret. 134.Pp 135The best way to allow easy, secure 136.Nm 137access is to create a local server socket in 138.Pa /etc/ppp/ppp.conf 139(in the correct section) like this: 140.Bd -literal -offset indent 141set server /var/run/internet "" 0177 142.Ed 143.Pp 144This will instruct 145.Nm ppp 146to create a local domain socket, with srw------- permissions and no 147password, allowing access only to the user that invoked 148.Nm ppp . 149Refer to the 150.Xr ppp 8 151man page for further details. 152.Pp 153You can now create some easy-access scripts. To connect to the internet: 154.Bd -literal -offset indent 155#! /bin/sh 156test $# -eq 0 && time=300 || time=$1 157exec pppctl /var/run/internet set timeout $time\\; dial 158.Ed 159.Pp 160To disconnect: 161.Bd -literal -offset indent 162#! /bin/sh 163exec pppctl /var/run/internet set timeout 300\\; close 164.Ed 165.Pp 166To check if the line is up: 167.Bd -literal -offset indent 168#! /bin/sh 169pppctl -p '' -v /var/run/internet quit | grep ^PPP >/dev/null 170if [ $? -eq 0 ]; then 171 echo Link is up 172else 173 echo Link is down 174fi 175.Ed 176.Pp 177You can even make a generic script: 178.Bd -literal -offset indent 179#! /bin/sh 180exec pppctl /var/run/internet "$@" 181.Ed 182.Pp 183You could also use 184.Nm 185to control when dial-on-demand works. Suppose you want 186.Nm ppp 187to run all the time, but you want to prevent dial-out between 8pm and 8am 188each day. However, any connections active at 8pm should continue to remain 189active until they are closed or naturally time out. 190.Pp 191A 192.Xr cron 8 193entry for 8pm which runs 194.Bd -literal -offset indent 195pppctl /var/run/internet set filter dial 0 deny 0 0 196.Ed 197.Pp 198will block all further dial requests, and the corresponding 8am entry 199.Bd -literal -offset indent 200pppctl /var/run/internet set filter dial -1 201.Ed 202.Pp 203will allow them again. 204.Sh SEE ALSO 205.Xr ps 1 , 206.Xr editline 3 , 207.Xr editrc 5 , 208.Xr services 5 , 209.Xr ppp 8 210.Sh HISTORY 211The 212.Nm 213utility first appeared in 214.Fx 2.2.5 . 215