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.2 2003/06/17 04:30:01 dillon 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 EXAMPLES 104If you run 105.Nm ppp 106in 107.Fl auto 108mode, 109.Nm 110can be used to automate many frequent tasks (you can actually control 111.Nm ppp 112in any mode except interactive mode). Use of the 113.Fl p 114option is discouraged (even in scripts that aren't readable by others) 115as a 116.Xr ps 1 117listing may reveal your secret. 118.Pp 119The best way to allow easy, secure 120.Nm 121access is to create a local server socket in 122.Pa /etc/ppp/ppp.conf 123(in the correct section) like this: 124.Bd -literal -offset indent 125set server /var/run/internet "" 0177 126.Ed 127.Pp 128This will instruct 129.Nm ppp 130to create a local domain socket, with srw------- permissions and no 131password, allowing access only to the user that invoked 132.Nm ppp . 133Refer to the 134.Xr ppp 8 135man page for further details. 136.Pp 137You can now create some easy-access scripts. To connect to the internet: 138.Bd -literal -offset indent 139#! /bin/sh 140test $# -eq 0 && time=300 || time=$1 141exec pppctl /var/run/internet set timeout $time\\; dial 142.Ed 143.Pp 144To disconnect: 145.Bd -literal -offset indent 146#! /bin/sh 147exec pppctl /var/run/internet set timeout 300\\; close 148.Ed 149.Pp 150To check if the line is up: 151.Bd -literal -offset indent 152#! /bin/sh 153pppctl -p '' -v /var/run/internet quit | grep ^PPP >/dev/null 154if [ $? -eq 0 ]; then 155 echo Link is up 156else 157 echo Link is down 158fi 159.Ed 160.Pp 161You can even make a generic script: 162.Bd -literal -offset indent 163#! /bin/sh 164exec pppctl /var/run/internet "$@" 165.Ed 166.Pp 167You could also use 168.Nm 169to control when dial-on-demand works. Suppose you want 170.Nm ppp 171to run all the time, but you want to prevent dial-out between 8pm and 8am 172each day. However, any connections active at 8pm should continue to remain 173active until they are closed or naturally time out. 174.Pp 175A 176.Xr cron 8 177entry for 8pm which runs 178.Bd -literal -offset indent 179pppctl /var/run/internet set filter dial 0 deny 0 0 180.Ed 181.Pp 182will block all further dial requests, and the corresponding 8am entry 183.Bd -literal -offset indent 184pppctl /var/run/internet set filter dial -1 185.Ed 186.Pp 187will allow them again. 188.Sh ENVIRONMENT 189The following environment variables are understood by 190.Nm 191when in interactive mode: 192.Bl -tag -width XXXXXXXXXX 193.It Dv EL_SIZE 194The number of history lines. The default is 20. 195.It Dv EL_EDITOR 196The edit mode. Only values of "emacs" and "vi" are accepted. Other values 197are silently ignored. This environment variable will override the 198.Ar bind -v 199and 200.Ar bind -e 201commands in 202.Pa ~/.editrc . 203.El 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