   \input texinfo

Linux Dialin Server Setup Guide
*******************************

     Josh Gentry, `jgentry@swcp.com'
     v1.5, 14 November, 1999

   This document is a step-by-step guide to setting up a Linux dialin
server which provides SLIP and PPP connections over a phone line.
`Copyright'

   This document is distributed under the Linux Documentation Project
Copyright, available at urlnam.  It is not part of the Linux
Documentation Project, but I like their copyright.

   `Acknowledgements'

   Much information in this document was originally gleaned from the
following LDP HOWTOs:
   * Linux Serial HOWTO

   * Linux Modem HOWTO

   * Linux Kernel HOWTO

   * Linux PPP HOWTO

   A great deal of information was found in Gert Doering's online
documentation for mgetty+sendfax.  Additionally, the following online
documents were valuable in the configuration of AutoPPP in mgetty:
   * urlnam, Mick Dennis

   * urlnam, Kalevi Hautaniemi

   Much information on PAP was learned from Olaf Kirch's `Linux Network
Administrator's Guide' and the S.u.S.E Support Data Base at urlnam.

   The majority of this information was originally gathered for, or
derived from, the process of setting up a Linux Redhat 5.1 dialin
server for Mr. James Hart.  He teaches at the Technical/Vocational
Institute in Albuquerque, NM.  Tony Lucero was my partner on that
project.  Their help and guidance were invaluable.

   A big thank you to all those who have aided in the development of
the Linux kernel and Linux applications.  TThis document is my small
contribution to their effort.

   Finally, thank you to Henry Brown, whithout whom I might never have
become interested in networking.

   `Disclaimer'

   This document carries no explicit or implied warranty.  Nor is there
any guarantee that the information in this document is accurate.  It is
offered in the hopess of helping others, but you use it at your own
risk.  The author will not be liable for any damages that occur as a
result of using this document.  <!

Introduction
************

   A `dialin server' is a host equipped with a modem and phone line,
that allows other hosts with modems and phone lines to call and connect
to it.  There are several reasons a person might want to do this; to
use the resources on the dialin server, or, if the dialin server is on
a network, to use the dialin server to access the network.  Further, if
this LAN is connected to the Internet, the client may be able to access
the Internet via the dialin server.

Reason for document
===================

   The majority of information needed to setup a Linux Dialin Server is
available in LDP HOWTO's.  When I used these documents to setup such a
server, however, the fragmentary nature of the information was a major
obstacle.  This document consolidates much of the needed information
and presents it as a step-by-step guide.

This Document as Guide
======================

   Setting up a dialin server is a common project, but not a simple
one.  This document attempts to rigorously set fort a step-by-step
guide to the process.  It is likely, however, that you will need to
reference additional documents.  The LDP HOWTOs listed above should be
considered invaluable companions to this document, and should be
consulted in the order listed above.  Furthermore, do not neglect the
documentation included with your getty and PPP packages.

Clients and Servers
===================

   The protocols used to connect two hosts via a phone line are
technically `peer-to-peer' protocols; there is no real difference
between the machine that dials and the machine that is dialed into.
Conceptually, however, it is easier to think in `client/server' terms.
"When you dial into a site to establish a PPP connection, you are a
client.  The machine to which you connect is the server" (`Linux PPP
HOWTO', Hart).  I will use this convention throughout the document.

   Setting up a dialin server is the process of setting up a machine to
answer the phone, participate in the setup of a connection with the
client, and authenticate the client.

Differences Between Linux Distributions
=======================================

   My experience is with Redhat 5.1.  I believe most of the information
in this document will apply to all distributions.  Where I am aware of
or suspect differences between distributions, I will note it in the
text.

Software Packages Covered
=========================

   * Linux Kernel v2.0.34-urlnam

   * mgetty+sendfax-urlnam

   * PPP-2.3.3-urlnam

Modem Installation
******************

   For a host to be a dialin server, it must be physically possible to
dial into it.  This requires that the host have at least one modem and
phone line.  Modems are `serial devices', therefor it is highly
recommended that you read the Linux Serial HOWTO, as well as the Linux
Modem HOWTO.

Modem Type
==========

   Plug-and-Play modems are not well supported by Linux.  This means
that you want a jumperable modem or an external modem.  Start by asking
your vendor what brand they recommend.

Ports
=====

   `Serail ports', like all I/O ports, have an address.  By default,
Linux initializes four serial ports.  Some may be familiar with these
ports as Microsoft refers to them, COM 1-4.  In Linux these ports are
referred to asss ttyS0-ttyS3.  For example, the port known to Microsoft
as COM 1, would be known to Linux as ttyS0.

   Note that if you use a port address other than these four, you will
have to initialize that port with `setserial'.  See the `setserial' man
page.

   External modems plug into external serial ports (RS-232 ports) on
your PC.  These ports are automatically assigned an address by Linux.

   Internal modems plug into the internal PCI or ISA slots of your PC.
An interal modem is actually a modem `and a serial port'.  It carries
its own, and it is the modem's serial port that you plug into the
internal slot.  For these modems, you set the port address on the
modem.  This is why you want a `jumperable' modem.  You use the jumpers
to manually set address and IRQ.

   Note, if your PC has two external serial ports (RS-232), as most
PC's do, the `Linux Modem HOWTO' recommends setting your internal modem
address to ttyS2 or higher.

Kernel Support
**************

   Your Linux kernel must contain support for PPP.  It is very likely
that it already does.  Unless you did a very custom install  of your
Linux system, or have recompiled your kernel without PPP support, it is
there.

   In the unlikely event that you discover that your kernel does not
support, there is an easy way to remedy the problem.  Again, unless you
did a very custom install or excluded it when you recompiled your
kernel, your kernel will support loadable kernel modules.  The `insmod'
command is also probably installed on your system.  If so, it is as
simple as this:

          insmod slhc
          insmod ppp

   The command `lsmod' lists the loadable modules  currently installed
on your system.  There is also a command for removing modules.  For
more information, do a `man insmod.'

Kernel and Source Code
======================

   The kernel is a binary, an executable program.  Developers do not
write the kernel as an executable, they write code that is piped into a
`compiler', and the compiler produces the executable from that `source
code'.

   With Linux, you have the source code that is used to produce the
kernel executable.  This means that you can customize your kernel.  In
the unlikely event  that your kernel  does not support PPP or modules,
you will have to recompile it.  Unfortunately, recompiling the Linux
kernel is a task beyond the scope of this document.  Please reference
the Kernel HOWTO.

gettys
******

   You will need a getty that can handle modem communications.  Once
started, usually from `/etc/inittab', the getty runs as a backround
process.  Your modem getty will be idle until the modem receives a
call, at which point it will "answer" the phone and negotiate the
specifics of modem-to-modem communication with the client.  There are
several gettys that can be used for this task.  This document covers
the usage of mgetty.  You can aquire the mgetty+sendfax package and
documentation at Gert Doering's website, `http://www.leo.org/[tilde
]doering/mgetty'.  It was included with Redhat 5.1 and lived in
`/etc/mgetty+sendfax'.

   Note that anytime you see something like `/sbin/mgetty' that is
simply the path to the file.  Files may be located in different
locations in the directory structure on different machines, and
possible with differnt distributions.  Therefor, the path to the file
would be differnt.  You will need to verify the location of the
necessary files on your system.

   There are many options for mgetty that you can edit to your desired
configuration, most importantly in `/etc/mgetty+sendfax/mgetty.conf'.
Refer to the mgetty documentation if you need to make changes to the
default settings.  The default settings in
`/etc/mgetty+sendfax/mgetty.conf' worked for us.  If you wish to enable
AutoPPP, you will need to edit `/etc/mgetty+sendfax/login.config.'
Detailed instructions on that task appear later in this section.

   To start mgetty, edit `/etc/inittab'.  Here is another point where
the serial and modem HOWTO's are helpful.  You must tell mgetty which
serial port to monitor.  In Linux these ports are numbered 0-3, and
named `ttyS*' for dialin.  For a modem we installed on the third
internal port, we added this line to `/etc/inittab':

          S2:2345:respawn:/sbin/mgetty ttyS2 -D /dev/ttyS2

   The option "-D" tells mgetty to expect data only, no faxes.  After
this, issue the command `init q' to force initd to re-read
`/etc/inittab'.  This will cause mgetty to be started.

   Note that if you use a multi-port serial board, those ports might be
named differently than the four ports Linux initializes by default.  In
his excellent document on mgetty and AutoPPP, Mick Dennis reports
naming the ports on his Cyclade Cyclom 16YeP as `/dev/ttyC*'.

   Using the default settings, mgetty negotiates a `SLIP' (Serial Line
Internet Protocol) connection and allows authentication via
`/etc/passwd'.  This is a functional system that allows a user to login
to a shell account.  If desired, a mechanism can be provided to allows
users to start` pppd' after logging in over there SLIP connection.
First, to allow all users to execute pppd, issue the command:

          chmod u+s /usr/sbin/pppd

   Next, add this line to `/etc/bashrc':

          alias ppp="exec /usr/sbin/pppd -detach"

   This way, after the user has logged in over the SLIP connection,
they can start pppd by typing `ppp'.  This procedure is taken from
Robert Hart's `Linux PPP HOWTO'.  It is contriversial.  This approach
gives `ALL' users the ability to start pppd.  Many people feel that
this is secure enough for their purposes, but administrators more
woried about security object to this approach.  For more on this, see
the section `More on Seccurity' later in the document.

   Another option is to create a PPP account.  The entry in
`/etc/passwd' might look like this:

          ppp:x:351:230:pppclient:/home/ppp:/usr/sbin/pppd

   When a user connects they simply login as "ppp."  Once they provide
the password, pppd starts automatically.

   For Microsoft clients to work with this setup, the client must be
configured to provide a terminal screen after connection.  This is not
a default setting.  These are the steps to do it in Windows 95:

       1. Click on My Computer

       2. Click on Dial-Up Networking

       3. Right-click on the icon for the connection

       4. Click on Properties

       5. Click on Configure

       6. Click on Options

       7. Click box next to "Bring up terminal window after dialing"

AutoPPP and mgetty
==================

   Most Windows users will not like the requirement to use a login
screen after connecting to the server.  It is possible for the system
administrator to remove this annoying extra step by using mgetty's
ability to start pppd upon initiating a connection.  To do this, you
enable AutoPPP.

Compiling mgetty
================

   Note:  I have been told by several people, that when they chose to
install mgetty from  their Redhat 5.2 distribution mgetty was
automatically compiled to include AutoPPP.

   For AutoPPP to function, you must edit the makefile before
compiling.  On or near line 110 you will need this:

          CFLAGS=-02 -Wall -pipe -DAUTO_PPP

   After that edit, compile mgetty according to the mgetty
documentation instructions.  Next, you edit the
`/etc/mgetty+sendfax/login.config' to look like this around line 50:

          /AutoPPP/ -  -  /usr/sbin/pppd file /etc/ppp/options.server

   Once you have completed this configuration, mgetty will
automatically start pppd whne it receives the `LCP' configure request.
(For more on LCP read the pppd man page.)  The "file" option tells pppd
to read the file `/etc/ppp/options.server' instead of the default
`/etc/ppp/options'.  Since pppd uses `/etc/ppp/options' for acting as a
client or a server by default (remember, it is technically
peer-to-peer), using this option helps keep the desired options for
acting as a client or server seperate.

   Assuming that you have edited `/etc/mgetty+sendfax/mgetty.config' to
yourpreferences, you are done.  Note that in every instance that you
change options for a process, the process will have to be restarted
before the new options take affect.

   Note:  If you wish to be able to dial out with a modem that is being
monitored by mgetty, you will need to pay attention to what device your
communications program uses.  See urlnam.

PPP (Point-to-Point Protocol)
*****************************

   The Point-to-Point Protocol is the most popular protocol used for
connecting hosts by phone line.

Compiling PPP
=============

   Adhere to the PPP package documentation.  If you will be using
shadow passwords, you will need to use the following command:

          make HAS_SHADOW=1

   To use the MS-DNS options for Windows compatibility, and shadow, use:

          make USE_MS_DNS=1 HAS_SHADOW=1

   For more on this, see urlnam

Configuring pppd
================

   PPP is configured by editing the options files read by pppd in
`/etc/ppp'.  Remember that in this configuration pppd will read
`/etc/ppp/options.server' when it is started by mgetty.  The most
complete list of pppd options I have found is in the pppd man page.  If
you do not with to use PAP or CHAP, your file `/etc/ppp/options.server'
might look like this:

          -detach
          asyncmap 0
          modem
          crtscts
          lock
          proxyarp
          ms-dns aa.bb.cc.dd
          ms-dns ee.ff.gg.hh

   `-detach'-do not fork to become a backround process `asyncmap 0'-to
allow pppd to work over a rlogin/telnet connection `modem'-use the
modem control lines `crtscts'-use hardware flow control
`lock'-specifies that pppd use the UUCP-style lock on the serial device
`proxyarp'-adds and entry into the ARP table with the IP address of the
client and the IP addreess of the NIC `ms-dns'-specifies the address of
the DNS server to be used by Microsoft clients  (As far as I know,
there is no equivelent option for non-Microsoft clients.  A Linux
client must have the address of the DNS in `/etc/resolv.conf'.)

Configuring + PAP
=================

   `PAP' (Password Authentication Protocol) is one of the two protocols
that PPP uses to authenticate peers.  The other is `CHAP' (Challenge
Handshake Authentication Protocol).  CHAP is a more secure protocol,
but it is not as widely supported as PAP.  Thus, this document
addresses the use of PAP, only.  For more information on both PAP and
CHAP, see Olaf Kirch's `Linux Network Administrator's Guide'.

   Since PPP is technically a peer-to-peer protocol, PAP allows two-way
authentication.  This means that not only the "server" can request the
"client" to authenticate itself, but the reverse is also true.  The
"client" can require the "server" to authenticate itself.  In practice,
this is not often done.  Most PPP servers are not configured to
authenticate themselves to clients.

   It is not difficult to configure your PPP server to use PAP.  To the
`/etc/ppp/options.server' file above, simply add the following entry:

          require-pap
          refuse-chap

   With this configuration, pppd will check client login names and
passwords against the file ppp/pap-secrets.  The client will be granted
access only if it matches an entry in `/etc/ppp/pap-secrets'.  Example:

          #user         server       secret          addrs
          jdoe             *         password          *

   If the "server" and "addrs" fields are filled in, then the client
will only be granted access if the login name and password are sent
from the designated server and IP address/fully qualified domain name.

PAP using `/etc/passwd'
=======================

   If you do not wish to create an entry in `/etc/ppp/pap-secrets' for
each client allowed PPP access, you can instruct pppd to check login
names and passwords against `/etc/passwd' instead of
`/etc/ppp/pap-secrets'.  Add the option `login' to
`/etc/ppp/options.server'.  For this configuration, your
`/etc/ppp/options.server' file will look like this:

          -detach
          asyncmap 0
          modem
          crtscts
          lock
          require-pap
          refuse-chap
          login
          proxyarp
          ms-dns aa.bb.cc.dd
          ms-dns ee.ff.gg.hh

   If the "login" option is used, the file `/etc/ppp/pap-secrets' need
not exist.  In fact, it might interfere with the proper functioning of
PAP.  You can remove this file, or it can contain the following entry:

          * * "" *

   The advantage of maintaining `/etc/ppp/pap-secrets' with this line
is that it leaves you the option of denying PPP access to individual
accounts that have entries in `/etc/passwd'.  To do so, below the above
line, enter the following line:

          username * - *

   where "username" is the username of the account you wish to deny PPP
access.  Example:

          #user        server        secret        addrs
            *            *             ""           *
          jdoe           *              -           *

   There are many reasons you might want to shut out a particular user.
They might abuse the priviledge of dialin access to your server, or
simply not need access.  Any account allowed dialin access is a
potential entrance for intruders.  For this reason, any account that
does not require dialin access should not be allowed dialin access.

   When you use the `"login"' option with PAP, ALL users in
`/etc/passwd' are granted access, unless you deny them access in
`/etc/ppp/pap-secrets'.  If you look at your `/etc/passwd' file, you
will see that there are entries (or accounts) for several `processes'.
On my system, for example, accounts were created, by default, for:
root, bin, deamon, adm, lp, sync, shutdown, halt, mail, news, uucp,
operator, games, gopher, ftp, nobody and postgress.  These processes do
not need PPP dialin access.  If they are granted such access, as they
are when you use the `"login"' option with PAP, they are potential
security holes.  Thus, you should deny them access in
`/etc/ppp/pap-secrets' exactly the same way you do a human user.

          #user        server         secret         addrs
            *            *              """"           *
          jdoe           *               -             *
          root           *               -             *
          bin            *               -             *
          deamon         *               -             *
          etc.

IP Address Allocation with PPP
==============================

   For PPP to work, the client must have an IP address.  Most dialin
clients will not have their own IP address, so it is neccessary to
assign an IP address to the serial port that the client connects
through.

   Earlier, we created a PPP options file that specifies the
configuration of PPP connections the server will provide,
`/etc/ppp/options.server'.  It is also possible to create an options
file that is specific to connections made through a specified serial
port.  For example, to create a file for ttyS2, you create the file
`/etc/pp/options.ttyS2'.

   One of the options that can be defined in such a file is IP address
assigned to the port for PPP connections.  This is the format for this
option:

          ii.jj.kk.ll:mm.nn.oo.pp

   The first IP address, from left to right, is the IP address of the
server.  The second IP address is the IP address assigned to the serial
port for PPP connections.

   Note:  It is `extremely' important that you verify that the IP
address you assign to the serial port is a valid IP address on your
subnet, and that it is not assigned to any other device on the network.

More on security
****************

   What is involved here is a bit complicated, but very important.
Running pppd implies access to system files accessable only by root,
such as routing tables.  Thus pppd must be run under the UID of root.
Any user who wants to use PPP, however, must be able to execute pppd.
Linux provides a way to convince pppd that a non-root user attempting
to execute pppd is actually root, `SUID' (Set User ID).  Earlier in
this document the instructions are to use the command:

          chmod u+s /usr/sbin/pppd

   This would set the permissions for pppd  to something like:

          -rwsr-x--x  root  root  pppd

   What we do here is set the user ID (SUID) to root, as far as pppd is
concerned.  This. plus the "x" (for execute) allows any and all users
to execute pppd.  The problem with this is that if a user executes pppd
and then finds a way to make a system call or shell escape, they will
appear to the entire system as root.  Total system compromise.  (Thank
you to Paolo Milani for first pointing this out to me.)

   Developers work very hard to make pppd safe to run SUID to root, and
administrators have to live with the necessity of running pppd SUID to
root.  Administrators very concerned with security, however, will not
allow `all' users the right to execute pppd.  They will restrict this
right to only the users who must have it.  Thus, on your dialin server,
you might restrict the right to execute pppd to the users who are
allowed to dialin and dialout.

   To do this, create a `pppusers' group in `/etc/group'.  (Note:  It
may already exist.  In Redhat 5.1 it has the GID of 230.)  Make every
user you want to have PPP access a member of this group.  Then execute
these commands:

       1. chgrp pppusers /usr/sbin/pppd

       2. chmod 550 /usr/sbin/pppd

       3. chmod u+s /usr/sbin/pppd

   This sets the permissions for pppd to:

          -r-sr-x---  root  pppusers  /usr/sbin/pppd

   Now, only users belonging to the group pppusers can execute pppd.
This configuration provides a more secure dialin server.

Congradulations
***************

   You are done.

   Check out the further documentation recommended in the next section
of this document.

More Documentation and Related Links
************************************

   This author's documentation on other subjects:  urlnam

   Using and Managing PPP-This O'Reilly title fully lives up to
O'Reilly's reputation for excelence.  It thoroughly explains how PPP
works, what configuration options mean, and troubleshooting.  It also
covers such advanced topics as tunnelling and PPP over TCP.  I highly
recommend it.  Thank you to Andrew Sun for creating this excelent
resource.

   urlnam-Maker of multi-port serial boards and other remote access
networking devices.