From 76ba43c60a25fac9d529c486646000b5c9c07f09 Mon Sep 17 00:00:00 2001
From: binh <>
Date: Tue, 1 Feb 2005 23:00:32 +0000
Subject: [PATCH] Slowly getting there.... :) Removed Text-Terminal.xml,
Thin-Client.xml. Do not publish under any circumstances!!!! Binh.
---
.../Linux-Networking/About-the-Author.xml | 9 +-
.../Linux-Networking/Bandwidth-Limiting.xml | 781 +-
.../docbook/Linux-Networking/Database.xml | 3710 +---
.../Linux-Networking/Email-Hosting.xml | 3562 +---
LDP/guide/docbook/Linux-Networking/FTP.xml | 483 +-
.../Firewalling-and-Masquerading.xml | 15443 ----------------
LDP/guide/docbook/Linux-Networking/IPX.xml | 1939 +-
.../docbook/Linux-Networking/Internet.xml | 2 +-
.../docbook/Linux-Networking/Satellite.xml | 1428 --
.../Linux-Networking/Text-Terminal.xml | 8535 ---------
.../docbook/Linux-Networking/Thin-Client.xml | 5942 ------
.../Linux-Networking/Traffic-Control.xml | 2220 +--
LDP/guide/docbook/Linux-Networking/VNC.xml | 5926 ------
13 files changed, 25 insertions(+), 49955 deletions(-)
delete mode 100644 LDP/guide/docbook/Linux-Networking/Text-Terminal.xml
delete mode 100644 LDP/guide/docbook/Linux-Networking/Thin-Client.xml
diff --git a/LDP/guide/docbook/Linux-Networking/About-the-Author.xml b/LDP/guide/docbook/Linux-Networking/About-the-Author.xml
index 96f0d8dd..f4c75b18 100644
--- a/LDP/guide/docbook/Linux-Networking/About-the-Author.xml
+++ b/LDP/guide/docbook/Linux-Networking/About-the-Author.xml
@@ -42,7 +42,8 @@
Two of his technical documents have been incorporated into the
Linux Documentation Project ("Linux Dictionary" and "Linux Filesystem
- Hierarchy", www.tldp.org/guides.html). Furthermore, they are being
+ Hierarchy",
+ www.tldp.org/guides.html ). Furthermore, they are being
used as reference books in at least nine universities around the world
(University of Southern Queensland (Australia),
Universidad Michoacana (Mexico),
@@ -53,7 +54,11 @@
University of Ulster (Ireland),
Universität Duisburg-Essen (Germany),
Universidad Rey Juan Carlos (Spain),
- and Universiti Sains Malaysia (Malaysia)).
+ and Universiti Sains Malaysia (Malaysia)). As well as this, he is also a
+ Development Lead and Project Administrator of the "Computer Dictionary
+ Project"
+ http://computerdictionary.tsf.org.za/dictionary/index.html
+ which is being supported by the Shuttleworth Foundation.
diff --git a/LDP/guide/docbook/Linux-Networking/Bandwidth-Limiting.xml b/LDP/guide/docbook/Linux-Networking/Bandwidth-Limiting.xml
index f8f0d8e8..d0c2fb9b 100644
--- a/LDP/guide/docbook/Linux-Networking/Bandwidth-Limiting.xml
+++ b/LDP/guide/docbook/Linux-Networking/Bandwidth-Limiting.xml
@@ -12,786 +12,7 @@ is slow or our LAN users download tons of mp3s and the newest Linux
distro's *.iso files.
------------------------------------------------------------------------------
-
-2. Before We Start
-
-Let's imagine the following situation:
-
- * We have 115,2 kbits/s ppp (modem) internet link (115,2/10 = 11,5 kbytes/
- s). Note: with eth connections (network card) we would divide 115,2 by 8;
- with ppp we divide by 10, because of start/stop bits (8 + 1 + 1 = 10).
- * We have some LAN stations and their users are doing bulk downloads all
- the time.
- * We want web pages to open fast, no matter how many dowloads are
- happening.
- * Our internet interface is ppp0.
- * Our LAN interface is eth0.
- * Our network is 192.168.1.0/24
-
-
------------------------------------------------------------------------------
-2.1. What do we need
-
-
-Believe it or not, shaping the incoming traffic is an easy task and you don't
-have to read tons of books about routing or queuing algorithms. To make it
-work, we need at least Squid proxy; if we want to fine tune it, we will have
-to get familiar with ipchains or iptables and CBQ. To test our efforts,
-we can install IPTraf.
-
-
------------------------------------------------------------------------------
-
-2.2. How does it work?
-
-
-Squid is probably the most advanced HTTP proxy server available for Linux. It
-can help us save bandwidth in two ways:
-
-
- * The first is a main characteristic of proxy servers -- they keep
- downloaded web pages, pictures, and other objects in memory or on a disk.
- So, if two people are requesting the same web page, it isn't downloaded
- from the internet, but from the local proxy.
-
- * Apart from normal caching, Squid has a special feature called delay
- pools. Thanks to delay pools, it is possible to limit internet traffic in
- a reasonable way, depending on so-called 'magic words', existing in any
- given URL. For example, a magic word could be '.mp3', '.exe' or '.avi',
- etc. Any distinct part of a URL (such as .avi) can be defined as a magic
- word.
-
-
-With that, we can tell the Squid to download these kinds of files at a
-specified speed (in our example, it will be about 5 kbytes/s). If our LAN
-users download files at the same time, they will be downloaded at about 5
-kbytes/s altogether, leaving remaining bandwidth for web pages, e-mail, news,
-irc, etc.
-
-
-
-Of course, the Internet is not only used for downloading files via web pages
-(http or ftp). Later on, we will deal with limiting bandwidth for Napster,
-Realaudio, and other possibilities.
-
-
------------------------------------------------------------------------------
-
-3. Installing and Configuring Necessary Software
-
-
-Here, I will explain how to install the necessary software so that we can
-limit and test the bandwidth usage.
-
-
------------------------------------------------------------------------------
-
-3.1. Installing Squid with the delay pools feature
-
-
-As I mentioned before, Squid has a feature called delay pools, which allows
-us to control download bandwidth. Unfortunately, in most distributions, Squid
-is shipped without that feature.
-
-
-
-So if you have Squid already installed, I must disappoint you -- you need to
-uninstall it and do it once again with delay pools enabled in the way I
-explain below.
-
-
- 1. To get maximum performance from our Squid proxy, it's best to create a
- separate partition for its cache, called /cache/. Its size should be
- about 300 megabytes, depending on our needs.
-
- If you don't know how to make a separate partition, you can create the /
- cache/ directory on a main partition, but Squid performance can suffer a
- bit.
-
- 2. We add a safe 'squid' user:
-
- # useradd -d /cache/ -r -s /dev/null squid >/dev/null 2>&1
-
- No one can log in as squid, including root.
-
- 3. We download Squid sources from http://www.squid-cache.org
-
- When I was writing this HOWTO, the latest version was Squid 2.4 stable 1:
-
- [http://www.squid-cache.org/Versions/v2/2.4/squid-2.4.STABLE1-src.tar.gz]
- http://www.squid-cache.org/Versions/v2/2.4/squid-2.4.STABLE1-src.tar.gz
-
- 4. We unpack everything to /var/tmp:
-
- 5. # tar xzpf squid-2.4.STABLE1-src.tar.gz
-
- 6. We compile and install Squid (everthing is in one line):
-
- # ./configure --prefix=/opt/squid --exec-prefix=/opt/squid
- --enable-delay-pools --enable-cache-digests --enable-poll
- --disable-ident-lookups --enable-truncate --enable-removal-policies
-
- # make all
-
- # make install
-
-
------------------------------------------------------------------------------
-3.2. Configuring Squid to use the delay pools feature
-
- 1. Configure our squid.conf file (located under /opt/squid/etc/squid.conf):
-
-
-
- #squid.conf
- #Every option in this file is very well documented in the original squid.conf file
- #and on http://www.visolve.com/squidman/Configuration%20Guide.html
-
- #
- #The ports our Squid will listen on.
- http_port 8080
- icp_port 3130
- #cgi-bins will not be cached.
- acl QUERY urlpath_regex cgi-bin \?
- no_cache deny QUERY
- #Memory the Squid will use. Well, Squid will use far more than that.
- cache_mem 16 MB
- #250 means that Squid will use 250 megabytes of disk space.
- cache_dir ufs /cache 250 16 256
-
- #Places where Squid's logs will go to.
- cache_log /var/log/squid/cache.log
- cache_access_log /var/log/squid/access.log
- cache_store_log /var/log/squid/store.log
- cache_swap_log /var/log/squid/swap.log
- #How many times to rotate the logs before deleting them.
- #See the FAQ for more info.
- logfile_rotate 10
-
- redirect_rewrites_host_header off
- cache_replacement_policy GDSF
- acl localnet src 192.168.1.0/255.255.255.0
- acl localhost src 127.0.0.1/255.255.255.255
- acl Safe_ports port 80 443 210 119 70 20 21 1025-65535
- acl CONNECT method CONNECT
- acl all src 0.0.0.0/0.0.0.0
- http_access allow localnet
- http_access allow localhost
- http_access deny !Safe_ports
- http_access deny CONNECT
- http_access deny all
- maximum_object_size 3000 KB
- store_avg_object_size 50 KB
-
- #Set these if you want your proxy to work in a transparent way.
- #Transparent proxy means you generally don't have to configure all
- #your client's browsers, but hase some drawbacks too.
- #Leaving these uncommented won't do any harm.
- httpd_accel_host virtual
- httpd_accel_port 80
- httpd_accel_with_proxy on
- httpd_accel_uses_host_header on
-
- #all our LAN users will be seen by external web servers
- #as if they all used Mozilla on Linux. :)
- anonymize_headers deny User-Agent
- fake_user_agent Mozilla/5.0 (X11; U; Linux i686; en-US; rv:0.9.6+) Gecko/20011122
-
- #To make our connection even faster, we put two lines similar
- #to the ones below. They will point a parent proxy server our own Squid
- #will use. Don't forget to change the server to the one that will
- #be fastest for you!
- #Measure pings, traceroutes and so on.
- #Make sure that http and icp ports are correct.
-
- #Uncomment lines beginning with "cache_peer" if necessary.
- #This is the proxy you are going to use for all connections...
- #cache_peer w3cache.icm.edu.pl parent 8080 3130 no-digest default
-
- #...except for the connections to addresses and IPs beginning with "!".
- #It's a good idea not to use a higher
- #cache_peer_domain w3cache.icm.edu.pl !.pl !7thguard.net !192.168.1.1
-
- #This is useful when we want to use the Cache Manager.
- #Copy cachemgr.cgi to cgi-bin of your www server.
- #You can reach it then via a web browser typing
- #the address http://your-web-server/cgi-bin/cachemgr.cgi
- cache_mgr your@email
- cachemgr_passwd secret_password all
-
- #This is a name of a user our Squid will work as.
- cache_effective_user squid
- cache_effective_group squid
-
- log_icp_queries off
- buffered_logs on
-
-
- #####DELAY POOLS
- #This is the most important part for shaping incoming traffic with Squid
- #For detailed description see squid.conf file or docs at http://www.squid-cache.org
-
- #We don't want to limit downloads on our local network.
- acl magic_words1 url_regex -i 192.168
-
- #We want to limit downloads of these type of files
- #Put this all in one line
- acl magic_words2 url_regex -i ftp .exe .mp3 .vqf .tar.gz .gz .rpm .zip .rar .avi .mpeg .mpe .mpg .qt
- .ram .rm .iso .raw .wav .mov
- #We don't block .html, .gif, .jpg and similar files, because they
- #generally don't consume much bandwidth
-
- #We want to limit bandwidth during the day, and allow
- #full bandwidth during the night
- #Caution! with the acl below your downloads are likely to break
- #at 23:59. Read the FAQ in this bandwidth if you want to avoid it.
- acl day time 09:00-23:59
-
- #We have two different delay_pools
- #View Squid documentation to get familiar
- #with delay_pools and delay_class.
- delay_pools 2
-
- #First delay pool
- #We don't want to delay our local traffic.
- #There are three pool classes; here we will deal only with the second.
- #First delay class (1) of second type (2).
- delay_class 1 2
-
- #-1/-1 mean that there are no limits.
- delay_parameters 1 -1/-1 -1/-1
-
- #magic_words1: 192.168 we have set before
- delay_access 1 allow magic_words1
-
-
- #Second delay pool.
- #we want to delay downloading files mentioned in magic_words2.
- #Second delay class (2) of second type (2).
- delay_class 2 2
-
- #The numbers here are values in bytes;
- #we must remember that Squid doesn't consider start/stop bits
- #5000/150000 are values for the whole network
- #5000/120000 are values for the single IP
- #after downloaded files exceed about 150000 bytes,
- #(or even twice or three times as much)
- #they will continue to download at about 5000 bytes/s
-
- delay_parameters 2 5000/150000 5000/120000
- #We have set day to 09:00-23:59 before.
- delay_access 2 allow day
- delay_access 2 deny !day
- delay_access 2 allow magic_words2
-
-
- #EOF
-
-
-
-
- OK, when we have configured everything, we must make sure everything
- under /opt/squid and /cache directories belongs to user 'squid'.
-
-
-
- # mkdir /var/log/squid/
-
- # chown squid:squid /var/log/squid/
-
- # chmod 770 /var/log/squid/
-
- # chown -R squid:squid /opt/squid/
-
- # chown -R squid:squid /cache/
-
- Now everything is ready to run Squid. When we do it for the first time,
- we have to create its cache directories:
-
- # /opt/squid/bin/squid -z
-
- We run Squid and check if everything is working. A good tool to do that
- is IPTraf; you can find it on [http://freshmeat.net] http://
- freshmeat.net. Make sure you have set the appropriate proxy in your web
- browsers (192.168.1.1, port 8080 in our example):
-
- # /opt/squid/bin/squid
-
- If everything is working, we add /opt/squid/bin/squid line to the end of
- our initializing scripts. Usually, it can be /etc/rc.d/rc.local.
-
- Other helpful options in Squid may be:
-
- # /opt/squid/bin/squid -k reconfigure (it reconfigures Squid if we made
- any changes in its squid.conf file)
-
- # /opt/squid/bin/squid -help :) self-explanatory
-
- You can also copy cachemgr.cgi to the cgi-bin directory of your WWW
- server, to make use of a useful Cache Manager.
-
-
-
------------------------------------------------------------------------------
-3.3. Solving remaining problems
-
-
-OK, we have installed Squid and configured it to use delay pools. I bet
-nobody wants to be restricted, especially our clever LAN users. They will
-likely try to avoid our limitations, just to download their favourite mp3s a
-little faster (and thus causing your headache).
-
-
-
-I assume that you use IP-masquerade on your LAN so that your users could use
-IRC, ICQ, e-mail, etc. That's OK, but we must make sure that our LAN users
-will use our delay pooled Squid to access web pages and use ftp.
-
-
-
-We can solve most of these problems by using ipchains (Linux 2.2.x kernels)
-or iptables (Linux 2.4.x kernels).
-
-
------------------------------------------------------------------------------
-
-3.3.1. Linux 2.2.x kernels (ipchains)
-
-We must make sure that nobody will try to cheat and use a proxy server other
-than ours. Public proxies usually run on 3128 and 8080 ports:
-
-/sbin/ipchains -A input -s 192.168.1.1/24 -d ! 192.168.1.1 3128 -p TCP -j
-REJECT
-
-/sbin/ipchains -A input -s 192.168.1.1/24 -d ! 192.168.1.1 8080 -p TCP -j
-REJECT
-
-We must also make sure that nobody will try to cheat and connect to the
-internet directly (IP-masquerade) to download web pages:
-
-/sbin/ipchains -A input -s 192.168.1.1/24 -d ! 192.168.1.1 80 -p TCP -j
-REDIRECT 8080
-
-If everything is working, we add these lines to the end of our initializing
-scripts. Usually, it can be /etc/rc.d/rc.local.
-
-We might think to block ftp traffic (ports 20 and 21) to force our LAN users
-to use Squid, but it's not a good idea for at least two reasons:
-
- * Squid is a http proxy with ftp support, not a real ftp proxy. It can
- download from ftp, it can also upload to some ftp, but it can't delete/
- change name of files on remote ftp servers.
-
- When we block ports 20 and 21, we won't be able to delete/change name of
- files on remote ftp servers.
-
- * IE5.5 has a bug -- it doesn't use a proxy to retrieve the ftp directory.
- Instead it connects directly via IP-masquerade.
-
- When we block ports 20 and 21, we won't be able to browse through ftp
- directories, using IE5.5.
-
-
-So, we will block excessive ftp downloads using other methods. We will deal
-with it in chapter 4.
------------------------------------------------------------------------------
-
-3.3.2. Linux 2.4.x kernels (iptables)
-
-We must make sure that nobody will try to cheat and use a proxy server other
-than ours. Public proxies usually run on 3128 and 8080 ports:
-
-/sbin/iptables -A FORWARD -s 192.168.1.1/24 -d ! 192.168.1.1 --dport 3128 -p
-TCP -j DROP
-
-/sbin/iptables -A FORWARD -s 192.168.1.1/24 -d ! 192.168.1.1 --dport 8080 -p
-TCP -j DROP
-
-We must also make sure that nobody will try to cheat and connect to the
-internet directly (IP-masquerade) to download web pages:
-
-/sbin/iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 80 -j REDIRECT
---to-port 8080
-
-If everything is working, we add these lines to the end of our initializing
-scripts. Usually, it can be /etc/rc.d/rc.local.
-
-We might think to block ftp traffic (ports 20 and 21) to force our LAN users
-to use Squid, but it's not a good idea for at least two reasons:
-
- * Squid is a http proxy with ftp support, not a real ftp proxy. It can
- download from ftp, it can also upload to some ftp, but it can't delete/
- change name of files on remote ftp servers.
-
- When we block ports 20 and 21, we won't be able to delete/change name of
- files on remote ftp servers.
-
- * IE5.5 has a bug -- it doesn't use a proxy to retrieve the ftp directory.
- Instead it connects directly via IP-masquerade.
-
- When we block ports 20 and 21, our LAN users won't be able to browse
- through ftp directories, using IE5.5.
-
-
-So, we will block excessive ftp downloads using other methods. We will deal
-with it in chapter 4.
------------------------------------------------------------------------------
-
-4. Dealing with Other Bandwidth-consuming Protocols Using CBQ
-
-We must remember that our LAN users can spoil our efforts from chapter 3, if
-they use Napster, Kazaa or Realaudio. We must also remember that we didn't
-block ftp traffic in section 3.3.
-
-We will achieve it in a different way -- not by limiting downloading
-directly, but rather, indirectly. If our internet device is ppp0 and LAN
-device is eth0, we will limit outgoing traffic on interface eth0, and thus,
-limit incoming traffic to ppp0.
-
-To do it, we will get familiar with CBQ and cbq.init script. You can obtain
-it from [ftp://ftp.equinox.gu.net/pub/linux/cbq/] ftp://ftp.equinox.gu.net/
-pub/linux/cbq/. Download cbq.init-v0.6.2 and put it in /etc/rc.d/.
-
-You will also need iproute2 installed. It comes with every Linux
-distribution.
-
-Now look in your /etc/sysconfig/cbq/ directory. There, you should have an
-example file, which should work with cbq.init. If it isn't there, you
-probably don't have it compiled in your kernel nor it isnt't present as
-modules. Well, in any case, just make that directory, put example files
-provided below, and see if it'd work for you.
------------------------------------------------------------------------------
-
-4.1. FTP
-
-In chapter 3, we didn't block ftp for two reasons -- so that we could do
-uploads, and so that users with buggy IE5.5 could browse through ftp
-directories. In all, our web browsers and ftp programs should make downloads
-via our Squid proxy and ftp uploads/renaming/deleting should be made via
-IP-masquerade.
-
-We create a file called cbq-10.ftp-network in the /etc/sysconfig/cbq/
-directory:
-
-# touch /etc/sysconfig/cbq/cbq-10.ftp-network
-
-We insert the following lines into it:
-DEVICE=eth0,10Mbit,1Mbit
-RATE=15Kbit
-WEIGHT=1Kbit
-PRIO=5
-RULE=:20,192.168.1.0/24
-RULE=:21,192.168.1.0/24
-
-You will find the description of thses lines in cbq.init-v0.6.2 file.
-
-When you start /etc/rc.d/cbq.init-v0.6.2 script, it will read your
-configuration, which is placed in /etc/sysconfig/cbq/:
-
-# /etc/rc.d/cbq.init-v0.6.2 start
-
-If everything is working, we add /etc/rc.d/cbq.init-v0.6.2 start to the end
-of your initializing scripts. Usually, it can be /etc/rc.d/rc.local.
-
-Thanks to this command, your server will not send ftp data through eth0
-faster than about 15kbits/s, and thus will not download ftp data from the
-internet faster than 15kbits/s.Your LAN users will see that it's more
-efficient to use Squid proxy for doing ftp downloads. They will be also able
-to browse ftp directories using their buggy IE5.5.
-
-There is also another bug in IE5.5 - when you right click on a file in a ftp
-directory then select 'Copy To Folder', the file is downloaded not through
-proxy, but directly through IP-masquerade, thus omitting Squid with delay
-pools.
------------------------------------------------------------------------------
-
-4.2. Napster, Realaudio, Windows Media and other issues
-
-Here, the idea is the same as with ftp; we just add another port and set a
-different speed.
-
-We create file called cbq-50.napster-network in the /etc/sysconfig/cbq/
-directory:
-
-# touch /etc/sysconfig/cbq/cbq-50.napsterandlive
-
-Put these lines into that file:
-DEVICE=eth0,10Mbit,1Mbit
-RATE=35Kbit
-WEIGHT=3Kbit
-PRIO=5
-#Windows Media Player.
-RULE=:1755,192.168.1.0/24
-#Real Player uses TCP port 554, for UDP it uses different ports,
-#but generally RealAudio in UDP doesn't consume much bandwidth.
-RULE=:554,192.168.1.0/24
-RULE=:7070,192.169.1.0/24
-#Napster uses ports 6699 and 6700, maybe some other?
-RULE=:6699,192.168.1.0/24
-RULE=:6700,192.168.1.0/24
-#Audiogalaxy uses ports from 41000 to as high as probably 41900,
-#there are many of them, so keep in mind I didn't list all of
-#them here. Repeating 900 nearly the same lines would be of course
-#pointless. We will simply cut out ports 410031-41900 using
-#ipchains or iptables.
-RULE=:41000,192.168.1.0/24
-RULE=:41001,192.168.1.0/24
-#continue from 41001 to 41030
-RULE=:41030,192.168.1.0/24
-#Some clever users can connect to SOCKS servers when using Napster,
-#Audiogalaxy etc.; it's also a good idea to do so
-#when you run your own SOCKS proxy
-RULE=:1080,192.168.1.0/24
-#Add any other ports you want; you can easily check and track
-#ports that programs use with IPTraf
-#RULE=:port,192.168.1.0/24
-
-Don't forget to cut out remaining Audiogalaxy ports (41031-41900), using
-ipchains (kernels 2.2.x or iptables (kernels 2.4.x).
-
-Kernels 2.2.x.
-
-/sbin/ipchains -A input -s 192.168.1.1/24 -d ! 192.168.1.1 41031:41900 -p TCP
--j REJECT
-
-Kernels 2.4.x.
-
-/sbin/iptables -A FORWARD -s 192.168.1.1/24 -d ! 192.168.1.1 --dport 41031:
-41900 -p TCP -j REJECT
-
-Don't forget to add a proper line to your initializing scripts.
------------------------------------------------------------------------------
-
-5. Frequently Asked Questions
-
-5.1. Is it possible to limit bandwidth on a per-user basis with delay pools?
-
-Yes. Look inside the original squid.conf file and check the Squid
-documentation on [http://www.squid-cache.org] http://www.squid-cache.org
------------------------------------------------------------------------------
-
-5.2. How do I make wget work with Squid?
-
-It's simple. Create a file called .wgetrc and put it in your home directory.
-Insert the following lines in it and that's it!
-HTTP_PROXY=192.168.1.1:8080
-FTP_PROXY=192.168.1.1:8080
-
-You can make it work globally for all users, type man wget to learn how.
------------------------------------------------------------------------------
-
-5.3. I set up my own SOCKS server listening on port 1080, and now I'm not
-able to connect to any irc server.
-
-There can be two issues here.
-
-One is when your SOCKS proxy is open relay, that means everyone can use it
-from any place in the world. It is a security issue and you should check your
-SOCKS proxy configuration again - generally irc servers don't allow open
-relay SOCKS servers to connect to them.
-
-If you are sure your SOCKS server isn't open relay, you may be still
-disallowed to connect to some of the irc servers - it's because mostly they
-just check if SOCKS server is running on port 1080 of a client that is
-connecting. In that case just reconfigure your SOCKS to work on a different
-port. You will also have to reconfigure your LAN software to use a proper
-SOCKS server and port.
------------------------------------------------------------------------------
-
-5.4. I don't like when Kazaa or Audiogalaxy is filling up all my upload
-bandwidth.
-
-Indeed that can be painful, but it's simple to be solved.
-
-Create a file called for example /etc/sysconfig/cbq/cbq-15.ppp.
-
-Insert the following lines into it, and Kazaa or Audiogalaxy will upload not
-faster than about 15 kbits/s. I assume that your outgoing internet interface
-is ppp0.
-DEVICE=ppp0,115Kbit,11Kbit
-RATE=15Kbit
-WEIGHT=2Kbit
-PRIO=5
-TIME=01:00-07:59;110Kbit/11Kbit
-RULE=,:21
-RULE=,213.25.25.101
-RULE=,:1214
-RULE=,:41000
-RULE=,:41001
-#And so on till :41030
-RULE=,:41030
------------------------------------------------------------------------------
-
-5.5. My outgoing mail server is eating up all my bandwidth.
-
-You can limit your SMTP, Postfix, Sendmail, or whatever, in a way similar to
-the question above. Just change or add one rule:
-RULE=,:25
-
-Moreover, if you have an SMTP server, you can force your local LAN users to
-use it, even though they have set up their own SMTP servers to
-smtp.some.server! We'll do it in a transparent way we did before with Squid.
------------------------------------------------------------------------------
-
-5.6. Can I limit my own FTP or WWW server in a manner similar it is shown in
-the question above?
-
-Generally you can, but usually these servers have got their own bandwidth
-limiting configurations, so you will probably want to look into their
-documentation.
-
-2.2.x Kernels
-
-/sbin/ipchains -A input -s 192.168.1.1/24 -d ! 192.168.1.1 25 -p TCP -j
-REDIRECT 25
-
-2.4.x Kernels
-
-/sbin/iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 25 -j REDIRECT
---to-port 25
-
-Don't forget to add a proper line to your initializing scripts.
------------------------------------------------------------------------------
-
-5.7. Is it possible to limit bandwidth on a per-user basis with cbq.init
-script?
-
-Yes. Look inside this script; there are some examples.
------------------------------------------------------------------------------
-
-5.8. Whenever I start cbq.init, it says sch_cbq is missing.
-
-Probably you don't have CBQ as modules in your system. If you have compiled
-CBQ into your kernel, comment out the following lines in your cbq.init-v0.6.2
-script.
-### If you have cbq, tbf and u32 compiled into kernel, comment it out
-#for module in sch_cbq sch_tbf sch_sfq sch_prio cls_u32; do
-# if ! modprobe $module; then
-# echo "**CBQ: could not load module $module"
-# exit
-# fi
-#done
------------------------------------------------------------------------------
-
-5.9. CBQ sometimes doesn't work for no reason.
-
-Generally it shouldn't occur. Sometimes, you can observe mass downloads,
-though you think you have blocked all ports Napster or Audiogalaxy uses.
-Well, there is always one more port open for mass downloads. To find it, you
-can use IPTraf. As there can be possibly thousands of such ports, it can be
-really hard task for you. To make it easier, you can consider running your
-own SOCKS proxy - Napster, Audiogalaxy and many programs can use SOCKS
-proxies, so it's much easier to deal with just one port, than to do so with
-thousands of possibilites (standard SOCKS port is 1080, if you run your own
-SOCKS proxy server, you will be able to set it up differently, or run
-multiple instances of SOCKS proxy listening on different ports). Don't forget
-to close all ports for traffic, and leave open ports like 25 and 110 (SMTP
-and POP3), and other you think might be useful. You will find a link to
-awesome Nylon socks proxy server at the end of this HOWTO.
------------------------------------------------------------------------------
-
-5.10. Delay pools are stupid; why can't I download something at full speed
-when the network is used only by me?
-
-Unfortunately, you can't do much about it.
-
-The only thing you can do is to use cron and reconfigure it, for example, at
-1.00 am, so that Squid won't use delay pools, then reconfigure it again,
-let's say at 7.30 am, to use delay pools.
-
-To do this, create two separate config files, called for example
-squid.conf-day and squid.conf-night, and put them into /opt/squid/etc/.
-
-squid.conf-day would be the exact copy of a config we created earlier
-
-squid.conf-night, on the contrary, would not have any delay pool lines, so
-all you have to do is to comment them out.
-
-Next thing you have to do is to set up /etc/crontab entries correctly.
-
-Edit /etc/crontab and put the following lines there:
-#SQUID - night and day config change
-01 9 * * * root /bin/cp -f /opt/squid/etc/squid.conf-day /opt/squid/etc/squid.conf; /opt/squid/bin/squid -k reconfigure
-59 23 * * * root /bin/cp -f /opt/squid/etc/squid.conf-night /opt/squid/etc/squid.conf; /opt/squid/bin/squid -k reconfigure
------------------------------------------------------------------------------
-
-5.11. My downloads break at 23:59 with "acl day time 09:00-23:59" in
-squid.conf. Can I do something about it?
-
-You can achieve by removing that acl from your squid.conf, and "delay_access
-2 allow dzien delay_access 2 deny !dzien" as well.
-
-Then try to do it with cron as in the question above.
------------------------------------------------------------------------------
-
-5.12. Squid's logs grow and grow very fast, what can I do about it?
-
-Indeed, the more users you have, the more - sometimes useful - information
-will be logged.
-
-The best way to eradicate it would be to use logrotate, but you'd have to do
-a little trick to make it work with Squid: proper cron and logrotate entries.
-
-/etc/crontab entries:
-#SQUID - logrotate
-01 4 * * * root /opt/squid/bin/squid -k rotate; /usr/sbin/logrotate /etc/logrotate.conf; /bin/rm -f /var/log/squid/*.log.0
-
-Here we have caused logrotate to start daily at 04:01 am, so remove any
-remaining logrotate starting points, for example from /etc/cron.daily/.
-
-/etc/logrotate.d/syslog entries:
-#SQUID logrotate - will keep logs for 40 days
-/var/log/squid/*.log.0 {
-rotate 40
-compress
-daily
-postrotate
-/usr/bin/killall -HUP syslogd
-endscript
-}
------------------------------------------------------------------------------
-
-5.13. CBQ is stupid; why can't I download something at full speed when the
-network is used only be me?
-
-Lucky you, it's possible!
-
-There are to ways to achieve it.
-
-The first is the easy one, similar to the solution we've made with Squid.
-Insert a line similar to the one below to your CBQ config files placed in /
-etc/sysconfig/cbq/:
-TIME=00:00-07:59;110Kbit/11Kbit
-
-You can have multiple TIME parameters in your CBQ config files.
-
-Be careful though, because there is a small bug in that cbq.init-v0.6.2
-script - it won't let you set certain times, for example 00:00-08:00! To make
-sure if everything is working correctly, start cbq.init-v0.6.2, and then
-within the time you set, type
-
-/etc/rc.d/cbq.init-v0.6.2 timecheck
-
-This is the example how the proper output should look like:
-
-[root@mangoo rc.d]# ./cbq.init start; ./cbq.init timecheck **CBQ: 3:44: class
-10 on eth0 changed rate (20Kbit -> 110Kbit) **CBQ: 3:44: class 40 on ppp0
-changed rate (15Kbit -> 110Kbit) **CBQ: 3:44: class 50 on eth0 changed rate
-(35Kbit -> 110Kbit)
-
-In this example something went wrong, probably in the second config file
-placed in /etc/sysconfig/cbq/; second counting from the lowest number in its
-name:
-
-[root@mangoo rc.d]# ./cbq.init start; ./cbq.init timecheck **CBQ: 3:54: class
-10 on eth0 changed rate (20Kbit -> 110Kbit) ./cbq.init: 08: value too great
-for base (error token is "08")
-
-The second way to make CBQ more intelligent is harder - it doesn't depend on
-time. You can read about it in the Linux 2.4 Advanced Routing HOWTO, and play
-with tc command.
------------------------------------------------------------------------------
+* Bandwidth Limiting HOWTO
6. Miscellaneous
diff --git a/LDP/guide/docbook/Linux-Networking/Database.xml b/LDP/guide/docbook/Linux-Networking/Database.xml
index 1bf99035..cc707d1c 100644
--- a/LDP/guide/docbook/Linux-Networking/Database.xml
+++ b/LDP/guide/docbook/Linux-Networking/Database.xml
@@ -13,3714 +13,8 @@ unheard of), and has recently been made open source. It also works well with PHP
lacking transaction support (due to speed concerns), a future version of MySQL will have this opt
- Connecting to MS SQL 6.x+ via Openlink/PHP/ODBC mini-HOWTO
- Zili Zhang, silen@silen.net
- 3.0, 1999-07-15
+* Connecting to MS SQL 6.x+ via Openlink/PHP/ODBC mini-HOWTO
- How to connect to MS SQL 6.x+ database server via ODBC functions of
- PHP3(3.0.1x or above) compiled with Openlink drivers under Linux.
- ______________________________________________________________________
-
- Table of Contents
-
-
- 1. Introduction
-
- 1.1 Copyright
- 1.2 Disclaimer
-
- 2. Openlink
-
- 2.1 On the Client
- 2.2 On the Server
- 2.3 Configuration Before Test
- 2.4 Text with
-
- 3. PHP
-
- 4. Example
-
- 5. FAQ
-
-
-
- ______________________________________________________________________
-
- 1. Introduction
-
- This document describes how to connect to MS SQL 6.x+ database server
- via ODBC functions of PHP3(3.0.1x or above) compiled with Openlink
- drivers under Linux.
-
- In the Unix world, people may hate to be invoked with any M$ related
- software. However, in the real world, the boss may require you to
- store data in a MS SQL database on NT and run web application on
- Linux. What to do? Quit the job or sit down to read this document? If
- you choose latter, I will give you a detailed installation guide so
- that you can keep the job for a while. It is a How-to guide, not a
- Why-so guide. So don't ask me why abc instead of cba. I don't know
- either.
-
- PHP is becoming more and more popular in web programmers, mainly
- because it can be configured to connect to various databases like
- Oracle, MySQL, Solid and so on. But for a MS SQL server, the problem
- is different. Though you can use PHP's Sybase-ct support features to
- directly connect to MSSQL, many people (at least me) prefer to connect
- via ODBC.
-
- Utilizing Openlink ODBC middleware, you can use those ODBC_xxxx
- functions to connect to all the database Openlink has a driver for.
- You have to install Openlink Linux client and Server middleware and
- re-compile PHP to support ODBC functions. In the end, I made a script
- sample for reference.
-
-
- 1.1. Copyright
-
- Copyright (c) 1999 by Zili Zhang
-
- Please freely copy and distribute (sell or give away) this document in
- any format. It's requested that corrections and/or comments be
- forwarded to the document maintainer. You may create a derivative work
- and distribute it provided that you:
-
-
- · Send your derivative work (in the most suitable format such as
- sgml) to the LDP (Linux Documentation Project) or the like for
- posting on the Internet. If not the LDP, then let the LDP know
- where it is available.
-
- · License the derivative work with this same license or use GPL.
- Include a copyright notice and at least a pointer to the license
- used.
-
- · Give due credit to previous authors and major contributors.
-
-
- If you're considering making a derived work other than a translation,
- it's requested that you discuss your plans with the current
- maintainer.
-
-
- 1.2. Disclaimer
-
- The following document is offered in good faith as comprising only
- safe configuration and procedures. No responsibility is accepted by
- the author for any loss or damage caused in any way to any person or
- equipment, as a direct or indirect consequence of following these
- instructions.
-
- This document was derived from the plain text entry found on
- http://www.silen.net/openlink-php-odbc.txt
- .
-
-
- 2. Openlink
-
- This step is a little bit complicated. You have to done works on both
- sides of your Linux client machine and NT server.
-
-
- 2.1. On the Client
-
-
- · From ftp://www.openlinksw.com/ ,
- download install.sh and likoxglc.taz (for a libc6 system) or
- likoxxxx.taz (for a libc5 system).
-
- · mkdir /usr/local/openlink
-
- · copy install.sh and likoxglc.taz into /usr/local/openlink
-
- · cd /usr/local/openlink
-
- · sh install.sh, the install script will ask you the owner and group
- of the program. It will extract things to odbcsdk directory under
- /usr/local/openlink and copy a .odbc.ini into the owner's home
- directory.
-
-
- 2.2. On the Server
-
-
- · From ftp://www.openlinksw.com/ ,
- download ntadm65x.zip onto your NT server.
- · unzip ntadm65x.zip
-
- · cd disk1 - directory of where you unzip the package.
-
- · execute setup and follow the instructions to install the Openlink
- middleware.
-
- · remember to start Openlink request broker from start menu or
- service control panel.
-
-
- 2.3. Configuration Before Test
-
-
- · keep the .odbc.ini file in your home directory.
-
- · copy the udbc.ini from the bin directory of Openlink middleware
- install directory to the /etc directory of client.
-
- · customize /etc/udbc.ini. In [dsn_sql6] section, change the host,
- database, username and password entries to fit your server
- settings. Here is part of my /etc/udbc.ini:
-
-
- [dsn_sql6]
- Host = 10.0.0.1
- ServerType = sql6
- ;ServerOptions =
- Database = pubs
- ;FetchBufferSize = 30
- UserName = sa
- Password = xxxxxxx
-
-
-
- · add to your environment
- LD_LIBRARY_PATH='/usr/local/openlink/odbcsdk/lib' and export it. In
- csh shell, type: setenv LD_LIBRARY_PATH
- /usr/local/openlink/odbcsdk/lib
-
-
- 2.4. Text with odbctest
-
-
- · cd /usr/local/openlink/odbcsdk/examples
-
- · ./odbctest
-
- · type: dsn=dsn_sql6
-
- · when 'sql>' appears, you can execute your sql clauses to test the
- connection.
-
-
-
- 3. PHP
-
- Now we have Openlink and can go to PHP compilation. Note for this
- version, PHP 3.0.10 or above is required to make things work.
-
- · From http://www.php.net , download
- php-3.0.11.tar.gz
-
- · Perform the following steps:
-
- gzip -dc php-3.0.11.tar.gz|tar -xof -
-
- cd php-3.0.11
-
- ./configure --with-openlink (--with-mysql --with-gd=/usr/local/gd1.3 --enable-track-vars)
-
- NOTE: My configuration is to run PHP as CGI mode, support mysql,
- as well. Your configuration may be different.
-
- make --silent
-
- NOTE: Don't mind if there are warning messages.
-
- make install
-
-
-
- These will install php executable into /usr/local/bin. Before you
- execute php, copy the library files under /usr/local/open
- link/odbcsdk/lib into /usr/lib to make it easier for php to find open
- link libraries (I know there are better methods).
-
-
-
- 4. Example
-
- Please refers to PHP manual for ODBC functions. Here is my example
- code odbc.php3: (Note that odbc_num_rows() will not return anything,
- so you must repeately call odbc_fetch_row() to get that number.)
-
-
-
-
- /* some environment variables, you can test to comment them out to see
- * if things still work.
- */
- putenv("LD_LIBRARY_PATH=/usr/local/openlink/odbcsdk/lib");
- putenv("UDBCINI=/etc/udbc.ini");
- putenv("ODBCINI=/root/.odbc.ini");
- putenv("DebugFile=/tmp/udbc.out"); // debug trace output
-
- $dsn="DSN=dsn_main"; // note 'DSN=' is required
- $user="sa";
- $password="xxxxxxx";
-
- $sql="SELECT * FROM titles";
-
- /* directly execute mode */
- if ($conn_id=odbc_connect("$dsn",$user,$password)){
- echo "connected to DSN: $dsn ";
- if($result_id=odbc_do($conn_id, $sql)) {
- echo "executing '$sql' ";
- $num_fields=odbc_num_fields($result_id);
- if($num_fields>0){
- echo "Number of fields:
- $num_fields ";
- for($i=1;$i<=$num_fields;$i++){
-
- $field_name[$i-1]=odbc_field_name($result_id,$i);
- }
- $num_rows=0;
- while(odbc_fetch_row($result_id)){
- for($i=1;$i<=$num_fields;$i++){
-
- $result[$num_rows][$field_name[$i-1]]=odbc_result($result_id,$i);
- }
- $num_rows++;
- }
- echo "Number of rows: $num_rows ";
- }else{
- echo "not a field returned. ";
- }
- echo "Results: ";
- for($i=0;$i";
- }
- }
- echo "freeing result ";
- odbc_free_result($result_id);
- }else{
- echo "can not execute '$sql' ";
- }
- echo "closing connection $conn_id";
- odbc_close($conn_id);
- }else{
- echo "can not connect to DSN: $dsn ";
- }
- ?>
-
-
-
- 5. FAQ
-
-
-
- · Does this exact procedure work for MSSQL 7.0?
-
- Yes, Openlink will upgrade their software to 7.0, but I don't know
- when.
-
-
-
- · I followed this document step by step to install the openlink
- drivers but I stopped at the "install ntadm65x.zip" step. After I
- installed ntadm65x I tried to start the OpenLink Request Broker and
- got the error:
-
-
-
- unable to open the service control manager <5>
- press RETURN to exit oplrqb
-
-
-
- Could you please tell me how I can fix that problem?
-
- This should be a problem with NT itself. try restart the computer and
- then start openlink service from Control Panel/service manager.
-
-Sybase-PHP-Apache mini-HOWTO
-
-Tyson Lloyd Thwaites
-
-tyson.lloydthwaites@ite.com.au
-Revision History
-Revision 1.3 2001-07-11 Revised by: TLT
-Fixed example PHP script.
-Revision 1.2 2001-06-13 Revised by: TLT
-Shane Gelven pointed out an error in the init script paths.
-Revision 1.1 2001-05-29 Revised by: TLT
-Updated environment configuration section, changed HOWTO name.
-
-
-This HOWTO explains how to set up a Linux machine to run an Apache web server
-using PHP to access a Sybase-ASE database.
-
------------------------------------------------------------------------------
-Table of Contents
-1. Copyright and License
-2. Install Linux
-3. Install Sybase
-4. Configure Environment
- 4.1. Preconfigure Apache
-
-
-5. Install PHP
-6. Install Apache
-7. Test the System
-8. Post Install Tasks
-
-1. Copyright and License
-
-This document is copyright 2001 by Tyson Lloyd Thwaites, and is released
-under the terms of the GNU Free Documentation License, which is hereby
-incorporated by reference. Send feedback to tyson.lloydthwaites@ite.com.au.
------------------------------------------------------------------------------
-
-2. Install Linux
-
-This howto assumes you have already installed a working Linux system. This
-howto is based on a Redhat 6.2 system. I would appreciate any feedback on
-setting this up on other distros.
-
-The first thing you will have to do is uninstall the apache and mod_php rpms.
-Try the following:
- # rpm -e apache
- # rpm -e httpd
- # rpm -e mod_php
- # rpm -e php
-
-That should get rid of them. Just to be sure, run this:
- # rpm -qa | less
-
-and check that there is nothing to do with Apache or PHP left on you system.
------------------------------------------------------------------------------
-
-3. Install Sybase
-
-Download the Sybase-ASE files from [http://linux.sybase.com]
-linux.sybase.com. Sybase-ASE 11.0.3.3 is free for production. This howto
-refers to that version.
-
-First, install the Sybase RPMS as root:
- # rpm -ivh sybase-ase-11_0_3_3-6_i386.rpm
- # rpm -ivh sybase-doc-11_0_3_3-6_i386.rpm
- # rpm -ivh sybase-ocsd-10_0_4-6_i386.rpm
-
-For information on how to configure Sybase, read the instructions in the file
-/opt/sybase/doc/howto/howto-ase-quickstart.html. This document is very good,
-so we shouldn't need any more information here.
-
-
- Hint: After you have installed the sample database and run a select
- against it, you can stop following the instructions. The rest of the
- howto goes on to uninstall the sample database, but we want to keep it
- for testing later.
-
- NOTE: Some people have reported problems with the way the Sybase init
- scripts try to guess the Sybase directory. If you see the following
- error:
- export: sybase-ase-11.0.3.3: not a legal variable name
-
- when trying to run sybinstall.sh, then you need to edit the
- sybinstall.sh. Open the script and find the following lines (around line
- 104):
- # export SYBASE=/opt/sybase
- export SYBASE=`rpm -q --queryformat \
- '%{installprefix}\n' sybase-ase-11.0.3.3`
-
- Change these lines so they look like this:
- export SYBASE=/opt/sybase
- #export SYBASE=`rpm -q --queryformat \
- # '%{installprefix}\n' sybase-ase-11.0.3.3`
-
- This hardcodes the SYBASE path to /opt/sybase. If you did install Sybase
- somewhere non-standard and you get this error, you will have to change
- this path to point to your Sybase directory.
-
------------------------------------------------------------------------------
-4. Configure Environment
-
-After installing Sybase, you need to setup the Linux environment in order to
-allow clients to connect to the dataserver.
-
-The first thing we need to do is to set certain environment variables in /etc
-/profile. Open /etc/profile as super user and insert the following lines:
- export SYBASE=/opt/sybase
- export SYBPLATFORM=linux
- export LD_LIBRARY_PATH=$SYBASE/lib
- export LC_ALL=default
- export PATH="$SYBASE/bin:$PATH"
- export DSQUERY=SYBASE
-
-Next you need to change to permissions of the Sybase directory. This fixes
-some problems where PHP is unable to connect to the Sybase server. Run the
-following command as super user:
-chown -R sybase:sybase /opt/sybase
-
-To test whether your Sybase environment works, type the following:
- # su - nobody
- $ isql -Usa -P
- 1> sp_helpdb
- 2> go
-
-You should see a list of databases. To test whether you can use the sample
-datebase, now type:
- 1> use pubs2
- 2> go
- 1> select * from titles
- 2> go
-
-If you a list, you have sucessfully set up Sybase.
-
-
- NOTE: You may need to do the following in order for PHP to be able to
- access Sybase. Edit the file /opt/sybase/install/rc.sybase and remove the
- line that says:
- unset LANG; unset LC_ALL; \
-
- I don't know why that line is there, but it can stuff things up.
-
- NOTE: Some people have reported problems with the way the Sybase init
- scripts try to guess the Sybase directory. If you see the following
- error:
- errorerwerqwerqwerwerwer
-
- when trying to run sybinstall.sh or rc.sybase, then you need to change
-
-You may also want to add sybase to the list of services to run at boot time.
-To do this execute the following commands:
- # ln -s /opt/sybase/install/rc.sybase /etc/rc.d/init.d/sybase
- # ln -s /etc/rc.d/init.d/sybase /etc/rc.d/rc3.d/S15sybase
- # ln -s /etc/rc.d/init.d/sybase /etc/rc.d/rc3.d/K15sybase
-
-Now Sybase will start whenever you boot into runlevel 3.
-
-
- NOTE: The note for
-
------------------------------------------------------------------------------
-4.1. Preconfigure Apache
-
-Download and unpack the latest Apache distribution. In the Apache directory
-issue the following command:
- # ./configure --prefix=/usr/local/apache
-
-I think the 'prefix' value specifies where you want to store your html files;
-I just set it to the same as the apache install directory, where Apache will
-put its files when you run 'make install'.
------------------------------------------------------------------------------
-
-5. Install PHP
-
-Download the latest PHP distribution and unpack it.
-
-Change to the php directory and run the configure script. You need to pass
-certains options to the script. To enable PHP access Sybase, you need
---with-sybase-ct. You will also need to specify the web server interface to
-use; in our case, this is Apache, so we use --with-apache To build a CGI
-version of PHP, (which is also very useful as a shell scripting tool), just
-leave out the --with-apache.
-
-Here is a complete configure script with the above two options, as well as a
-number of other options that are useful.
- # ./configure --with-apache=../apache_1.3.19
- --with-sybase-ct=/opt/sybase --enable-bcmath --enable-calendar
- --enable-ctype --enable-exif --enable-ftp --enable-gd-imgstrttf
- --with-gd --enable-trans-sid --enable-shmop --enable-sockets
- --enable-sysvsem --enable-sysvshm --enable-wddx
-
-You will need to change to apache path to wherever you unpacked your apache
-distribution.
-
-If the configure scripts completes successfully, you can then proceed:
- # make && make install
-
-PHP should compile without any hitches. After it has installed, you need to
-install the php.ini file:
- # cp php.ini-optimized /usr/local/lib/php.ini
-
-Now we need to change a few things in /usr/local/lib/php.ini. Set the
-following parameters to the ones specified below:
- magic_quotes_sybase = on
- sybct.min_server_severity = 11
- sybct.min_client_severity = 11
-
-I also like to set the following:
- register_globals = on
- include_path=.:/usr/local/lib/php
-
-You have now completed the PHP installation.
------------------------------------------------------------------------------
-
-6. Install Apache
-
-Now cd back into the apache unpack directory. Issue the following commmands:
- # ./configure --activate-module=src/modules/php4/libphp4.a
- # make && make install
-
-This should proceed without any problems. When its done, edit the file /usr/
-local/apache/conf/httpd.conf and uncomment the following line:
- AddType application/x-httpd-php .php
-
-This tells apache to allow PHP to process files with a .php extension. You
-may also want to add some other extensions to the end of this line, eg:
- AddType application/x-httpd-php .php .php3 .html .htm
-
-You now have all the software you need and are ready to test your system.
------------------------------------------------------------------------------
-
-7. Test the System
-
-First, make sure Apache and Sybase are started:
- # /usr/local/apache/bin/apachectl start
- # /opt/sybase/install/rc.sybase start
-
-Now go to the directory /usr/local/apache/htdocs. Create a file called
-test.php and insert the following contents:
-
-
-Save the file and then access the following URL in your browser:
- http://localhost/test.php
-
-If you see some text, then congratulations! You have a complete Linux/Apache/
-PHP/Sybase-ASE installation. If not...well, there you go. Make sure you
-actually have installed the pubs2 database. If you are not sure, try running:
- # isql -Usa -P < /opt/sybase/scripts/installpubs2
-
-[mailto:tyson.lloydthwaites@ite.com.au] Email me if you have any problems,
-corrections (please!) or additions, but please do not email me unless you
-have tried everything in this howto! Thanks.
------------------------------------------------------------------------------
-
-8. Post Install Tasks
-
-After you have a working system, first of all, breath a deep sigh of
-satisfaction. (I also suggest eating something.) After this, there are a few
-post-install tasks you should perform.
-
-The FIRST thing you should do is change the password for the 'sa' user. By
-default this password is blank. To set a password for sa, type the following
-in isql:
- 1> sp_password null, 'new_pass123', 'sa'
- 2> go
-
-This will set the password. You will now need to pass this as a parameter to
-sybase_connect. You will also need to specify it when starting isql, which
-you can do by using the '-P' switch.
-
-
- NOTE: Once you have ste a password, you cannot unset it. (Sybase requires
- a minumum of six characters in a password, so '' won't be accepted.)
-
-You also may wish to install the Windows client tools. These can be found on
-a CD if you bought a cope of ASE from Sybase. Otherwise, if you are using the
-free 11.0.3.3 version, you can download a demo of ASE 12.0 for NT, and only
-install the 'ASE Plugin for Sybase Central', 'ASE ODBC Driver' and 'Sybase
-Central' components.
-
-
- : I am not sure of the licensing issues involved in using the client
- tools if you haven't purchased ASE. Although I don't think it would be a
- problem, you should contact Sybase directly if you want to be sure.
-
-I am open to more hints to put in this section.
-
-Sybase Adaptive Server Anywhere for Linux HOWTO
-
-Aylwin Lo
-
-Tom Slee
-
-Sybase Inc.
-
- Tom.Slee@sybase.com
-
-Revision History
-Revision 1.0 2001-04-26 Revised by: al
-First public release.
-
-
-This HOWTO guides you through the installation of SQL Anywhere Studio 7.0.2
-for Linux and the basic operation and administration of Adaptive Server
-Anywhere databases.
-
------------------------------------------------------------------------------
-Table of Contents
-1. Introduction
- 1.1. New versions of this document
- 1.2. Content and Audience
- 1.3. Adaptive Server Anywhere features
- 1.4. Quirks
- 1.4.1. Alt and Function keys
-
-
- 1.5. What's a Relational Database?
- 1.5.1. Definition
- 1.5.2. Example
- 1.5.3. Primary and Foreign Keys
-
-
-
-
-2. Requirements
- 2.1. System requirements
- 2.2. Supported distributions
-
-
-3. Installation
- 3.1. Process
- 3.2. Distribution-specific considerations (for TurboLinux and Caldera)
- 3.3. Setting the Environment Variables
- 3.4. Where did it get installed?
-
-
-4. Creating, Running and Connecting to Databases
- 4.1. Creating a database
- 4.1.1. Creating a database from the command prompt
- 4.1.2. Creating a database from Sybase Central
-
-
- 4.2. Running a database server and starting databases
- 4.2.1. Running the server as a daemon
-
-
- 4.3. Stopping the database server
- 4.4. Stopping databases
- 4.5. Connecting to a database
- 4.5.1. Connection strings
- 4.5.2. Connecting from Interactive SQL
- 4.5.3. Connecting via ODBC
- 4.5.3.1. Setting up ODBC with Adaptive Server Anywhere
- 4.5.3.2. About ODBC data sources
- 4.5.3.3. Connecting to an ODBC data source
-
-
-
-
-
-
-5. Backing up and Restoring a Database
- 5.1. Creating a Backup of the Database
- 5.1.1. Full vs. Incremental Backups
- 5.1.2. Online vs. Offline Backups
- 5.1.3. Server-side vs. Client-side Backups
- 5.1.4. How to make a backup
- 5.1.4.1. From the command line
- 5.1.4.2. From SQL
- 5.1.4.3. From Sybase Central
-
-
-
-
- 5.2. Validating the database and its backup
- 5.3. Recovering the database
-
-
-6. Managing a Database
- 6.1. Tables
- 6.1.1. Creating a Table
- 6.1.2. Making Alterations to Tables
-
-
- 6.2. Users, permissions, and authorities
- 6.2.1. User IDs
- 6.2.1.1. Special user IDs
- 6.2.1.2. Creating new user IDs
-
-
- 6.2.2. Permissions
- 6.2.3. Authorities
- 6.2.3.1. RESOURCE authority
- 6.2.3.2. DBA authority
-
-
- 6.2.4. Removing Users and Revoking Permissions
- 6.2.5. Changing Passwords
-
-
- 6.3. Making the database more secure
- 6.3.1. Increasing password security
- 6.3.2. Views, procedures, and triggers
- 6.3.3. Encrypting client/server communications
-
-
-
-
-7. Where to get more information
-8. Legalities and Acknowledgements
- 8.1. Copyright and Licenses
- 8.2. Names and Contacts
- 8.3. Acknowledgement
-
-
-
------------------------------------------------------------------------------
-1. Introduction
-
-This HOWTO guides you through the installation of SQL Anywhere Studio 7.0.2
-for Linux and the basic operation and administration of Adaptive Server
-Anywhere databases.
------------------------------------------------------------------------------
-
-1.1. New versions of this document
-
-The latest version of this document should always be available at the Linux
-Documentation project website ([http://www.linuxdoc.org/] http://
-www.linuxdoc.org/).
------------------------------------------------------------------------------
-
-1.2. Content and Audience
-
-Within this document, you will find a list of the supported Linux
-distributions ("Section 2"). It is intended for moderately experienced users
-of Linux or UNIX. Familiarity with relational database concepts is certainly
-useful, but not a requirement. "Section 1.5" contains a summary of relational
-database concepts.
------------------------------------------------------------------------------
-
-1.3. Adaptive Server Anywhere features
-
-Adaptive Server Anywhere (Adaptive Server Anywhere) is the full SQL
-relational database management system at the heart of SQL Anywhere Studio.
-Ideally suited for use as an embedded database, in mobile computing, or as a
-workgroup server, it includes the following among its features:
-
- * Economical hardware requirements
-
- * Designed to operate without administration
-
- * Designed for mobile computing and synchronization
-
- * Ease of use
-
- * High performance
-
- * Cross-platform solution
-
- * Standalone and network use
-
- * Industry standard interfaces
-
-
-Some of the more specific features include:
-
- * Stored procedures and triggers
-
- * Java support for logic and datatypes
-
-
-For further details about Adaptive Server Anywhere, please visit the
-following links:
-
- * [http://www.sybase.com/detail/1,3693,1002624,00.html] http://
- www.sybase.com/detail/1,3693,1002624,00.html is a datasheet on SQL
- Anywhere Studio. It includes some data on Adaptive Server Anywhere, which
- ships as a component of SQL Anywhere Studio.
-
- * [http://www.sybase.com/detail/1,3693,1009210,00.html] http://
- www.sybase.com/detail/1,3693,1009210,00.html has some information on the
- features and system requirements of SQL Anywhere Studio and points you to
- the download location for SQL Anywhere Studio for Linux 7.0.
-
-
------------------------------------------------------------------------------
-1.4. Quirks
-
-1.4.1. Alt and Function keys
-
-Sometimes the Alt keys or the F1-F10 keys may not function in the terminal
-where you are running Interactive SQL.
-
-To emulate the Alt key, press Ctrl-A. Then press whatever key was to be
-pressed with the Alt key. For example, instead of pressing Alt-F, you would
-press Ctrl-A, then F.
-
-To emulate the function keys, press Ctrl-F, followed by the number of the
-function key you wanted to press. For example, instead of pressing F9, you
-would press Ctrl-F, then 9. For F10, use the zero key.
------------------------------------------------------------------------------
-
-1.5. What's a Relational Database?
-
-If you are already familiar with relational databases, you can skip this
-section.
------------------------------------------------------------------------------
-
-1.5.1. Definition
-
-A relational database-management system (RDBMS) is a system for storing and
-retrieving data, in which the data is organized in tables. A relational
-database consists of a collection of tables that store interrelated data.
-
-If that doesn't quite make sense yet, read on.
------------------------------------------------------------------------------
-
-1.5.2. Example
-
-Suppose you have some software to keep track of sales orders, and each order
-is stored in the form of a table, called sales_order. It has information
-about the customer (for example, her name, address and phone number), the
-date of the order, and information about the sales representative (for
-example his name, department, and office phone number). Let's put all this
-into a table, with the data for a few orders:
-
-
-Table 1. The sales_order table
-+-----------+---------------+--------------------+------------+-----------+------------+----------+------------+
-|cust_name |cust_address |cust_city_state_zip |cust_phone |order_date |emp_name |emp_dept |emp_phone |
-+-----------+---------------+--------------------+------------+-----------+------------+----------+------------+
-|M. Devlin |3114 Pioneer |Rutherford, NJ 07070|2015558966 |19930316 |R. Overbey |Sales |5105557255 |
-| |Ave. | | | | | | |
-+-----------+---------------+--------------------+------------+-----------+------------+----------+------------+
-|M. Devlin |3114 Pioneer |Rutherford, NJ 07070|2015558966 |19940405 |M. Kelly |Sales |5085553769 |
-| |Ave. | | | | | | |
-+-----------+---------------+--------------------+------------+-----------+------------+----------+------------+
-|J. |2800 Park Ave. |Hull, PQ K1A 0H3 |8195559539 |19940326 |M.Garcia |Sales |7135553431 |
-|Gagliardo | | | | | | | |
-+-----------+---------------+--------------------+------------+-----------+------------+----------+------------+
-|E. Peros |50 Market St. |Rochester, NY 14624 |7165554275 |19930603 |P. Chin |Sales |4045552341 |
-+-----------+---------------+--------------------+------------+-----------+------------+----------+------------+
-|E. Peros |50 Market St. |Rochester, NY 14624 |7165554275 |19940127 |M.Garcia |Sales |7135553431 |
-+-----------+---------------+--------------------+------------+-----------+------------+----------+------------+
-|E. Peros |50 Market St. |Rochester, NY 14624 |7165554275 |19940520 |J. Klobucher|Sales |7135558627 |
-+-----------+---------------+--------------------+------------+-----------+------------+----------+------------+
-
-Everything appears nice and ordered, but there's a fair bit of redundancy. M.
-Devlin's name appears twice, along with his address and phone number. E.
-Peros' details appear three times. If you look carefully at the employee side
-of things, you'll notice that M. Garcia is repeated, as well.
-
-Wouldn't it be nice if you could separate that information and only store it
-once, rather than several times? In the long term, it would certainly save
-disk space and allow for greater flexibility. Since redundant data entry is
-minimized, it would also reduce the chances of erroneous data entering the
-database, increasing consistency. Well, we can see three different entities
-involved here: the customer, the order, and the employee. So let's take each
-of the individuals, put them into categories, and give them identification
-numbers so they can be referenced.
-
-
-Table 2. The customer table
-+-----+------------+----------------+------------------+------------+
-|id |name |address |city_state_zip |phone |
-+-----+------------+----------------+------------------+------------+
-|101 |M. Devlin |3114 Pioneer |Rutherford, NJ |2015558966 |
-| | |Ave. |07070 | |
-+-----+------------+----------------+------------------+------------+
-|109 |J. Gagliardo|2800 Park Ave. |Hull, PQ K1A 0H3 |8195559539 |
-+-----+------------+----------------+------------------+------------+
-|180 |E. Peros |50 Market St. |Rochester, NY |7165554275 |
-| | | |14624 | |
-+-----+------------+----------------+------------------+------------+
-
-
-Table 3. The employee table
-+-----+-------------+-------+------------+
-|id |name |dept |phone |
-+-----+-------------+-------+------------+
-|299 |R. Overbey |Sales |5105557255 |
-+-----+-------------+-------+------------+
-|902 |M. Kelly |Sales |5085553769 |
-+-----+-------------+-------+------------+
-|667 |M.Garcia |Sales |7135553431 |
-+-----+-------------+-------+------------+
-|129 |P. Chin |Sales |4045552341 |
-+-----+-------------+-------+------------+
-|467 |J. Klobucher |Sales |7135558627 |
-+-----+-------------+-------+------------+
-
-
-Table 4. The new sales_order table
-+------+--------+-----------+-------------+
-|id |cust_id |order_date |sales_rep_id |
-+------+--------+-----------+-------------+
-|2001 |101 |19930316 |299 |
-+------+--------+-----------+-------------+
-|2583 |101 |19940405 |902 |
-+------+--------+-----------+-------------+
-|2576 |109 |19940326 |667 |
-+------+--------+-----------+-------------+
-|2081 |180 |19930603 |129 |
-+------+--------+-----------+-------------+
-|2503 |180 |19940127 |667 |
-+------+--------+-----------+-------------+
-|2640 |180 |19940520 |467 |
-+------+--------+-----------+-------------+
-
-As you can see, each customer's information is stored only once, and the same
-goes for each employee. The sales_order table is a lot smaller, too. Each
-row, representing a sales order, refers to a cust_id and an emp_id.
-
-By looking up the customer corresponding to a cust_id (which is unique), one
-can find all the needed data on that customer, without having to repeat it in
-sales_order. In addition, an id column has been added. Its purpose will be
-explained in the next section.
-
-Why do this, you ask? By eliminating redundancy, this kind of structure
-reduces the opportunities for inconsistencies to seep in, in addition to
-lowering storage requirements. If you had to change E. Peros' address in the
-old sales_order table, you'd have to do it three times, which would take
-three times as long and give you three times as many chances to make an
-error. In the newer table, all you'd have to do is change her address once,
-in the customer table. Also, by carefully separating data, you make access
-control simpler.
-
-Finally, can you spot another redundancy? The employee table has "Sales" all
-the way down the dept column. For an organization with multiple departments,
-you'd want to add a department table and reference it from a dept_id column
-instead.
------------------------------------------------------------------------------
-
-1.5.3. Primary and Foreign Keys
-
-As described in the previous section, you can separate a table into
-interrelated tables. But how do you go about relating tables to each other?
-In relational databases, primary keys and foreign keys help you link tables
-together. Primary keys are columns that uniquely identify each row of a
-table, and foreign keys define the relationship between the rows of two
-separate tables. Proper use of primary and foreign keys will help you
-efficiently hold information without excessive redundancy.
-
-Every table should have a primary key to ensure that each row is uniquely
-identified. This often takes the form of an ID number being assigned to each
-row, as in the previous section's example. The id column forms the primary
-key.
-
-As long as you can guarantee the uniqueness of the data in a particular
-column, though, that column can be a primary key. For example, if you only
-want one entry per day to be put into a particular table, you could use the
-date as that table's primary key.
-
-Tables are related to one another by foreign keys. In the sales_order
-example, the cust_id and sales_rep columns would be called foreign keys to
-the customer and employee tables, respectively. For terminology's sake, you
-might want to know that in this case, the sales_order table is called the
-foreign or referencing table, while the customer and employee tables are
-called the primary or referenced tables.
------------------------------------------------------------------------------
-
-2. Requirements
-
-2.1. System requirements
-
-Adaptive Server Anywhere requires that you have the following installed on
-your system:
-
- * kernel 2.2.5-15 and up (2.2.x series)
-
- * glibc-2.1 or up
-
- * pthreads-0.8 or higher (included usually as part of glibc)
-
- * libstdc++-2-libc6.1
-
-
------------------------------------------------------------------------------
-2.2. Supported distributions
-
-At present, the following Linux distributions are supported:
-
- * Caldera 2.4
-
- * Red Hat 7.0, 6.2, 6.1 or 6.0
-
- * TurboLinux 6.1
-
- * SuSE 7.0, 6.4, 6.3 or 6.2
-
-
-NOTE: The glibc and gcc released with Red Hat Linux 7.0 require patches
-before you can use Adaptive Server Anywhere. You can find them at [http://
-www.redhat.com/support/errata/rh7-errata-bugfixes.html] http://www.redhat.com
-/support/errata/rh7-errata-bugfixes.html.
------------------------------------------------------------------------------
-
-3. Installation
-
-3.1. Process
-
- 1. Log on as root.
-
- 2. Place the CD-ROM into the CD-ROM drive.
-
- 3. Mount the CD-ROM. Usually, it gets mounted to /mnt/cdrom. If so, enter
- the following command:
-
- mount /mnt/cdrom
-
- 4. At a command prompt, change to the CD-ROM directory. If the CD-ROM was
- mounted to /mnt/cdrom/, use the following command:
-
- cd /mnt/cdrom
-
- 5. Start the setup script by entering the following command:
-
- ./setup
-
- 6. The setup script prompts you with information about installing SQL
- Anywhere Studio for UNIX. Enter any information you are prompted for, and
- press the Enter key to continue.
-
-
-By default, SQL Anywhere Studio is installed into a directory named SYBSsa7
-under /opt/sybase on Solaris, Linux, and HP-UX, and under /usr/lpp/sybase on
-AIX. You can specify another installation directory if you wish.
------------------------------------------------------------------------------
-
-3.2. Distribution-specific considerations (for TurboLinux and Caldera)
-
-After installation, you should follow these instructions if you are running
-either TurboLinux 6.0 or Caldera 2.2.
-
-For TurboLinux 6.0 only, change to directory /usr/lib and create a symbolic
-link using the following command.
-
-ln -s libstdc++-libc6.1-2.so.3 libstdc++-libc6.1-1.so.2
-
-For Caldera 2.2 only, change to directory /usr/lib and create a symbolic link
-using the following command.
-
-ln -s /usr/lib/libstdc++-2.9.0 /usr/lib/libstdc++-libc6.1-1.so.2
------------------------------------------------------------------------------
-
-3.3. Setting the Environment Variables
-
-Each user who uses the software must set the necessary environment variables
-for Adaptive Server Anywhere. To help you do that, the installation program
-puts two script files, asa_config.sh and asa_config.csh, in the directory /
-InstallDir/SYBSsa7/bin. InstallDir is the directory where you chose to
-install Adaptive Server Anywhere.
-
-Depending on which shell you're using, enter the appropriate command from
-InstallDir.
-
-
-Table 5.
-+---------------------------+-------------------------------------+
-|If you're using this |...use this command. |
-|shell... | |
-+---------------------------+-------------------------------------+
-|sh, ksh, bash |. ./SYBSsa7/bin/asa_config.sh |
-+---------------------------+-------------------------------------+
-|csh, tcsh |source ./SYBSsa7/bin/asa_config.csh |
-+---------------------------+-------------------------------------+
-
-You may also want to insert the above commands into your copy of .profile or
-.bash_profile to have the environment variables ready every time you log in.
------------------------------------------------------------------------------
-
-3.4. Where did it get installed?
-
-Table 6.
-+---------------------------------------------------------------+-----------------------------------------+
-|Most Adaptive Server Anywhere command line utilities (names |/InstallDir/SYBSsa7/bin |
-|beginning with db) | |
-+---------------------------------------------------------------+-----------------------------------------+
-|Sybase Central |/InstallDir/shared/sybcentral40/java |
-+---------------------------------------------------------------+-----------------------------------------+
-|Sample database |/InstallDir/SYBSsa7 |
-+---------------------------------------------------------------+-----------------------------------------+
-|Online documentation |/CDROM/help/contents.htm or/InstallDir/ |
-| |SYBSsa7/doc/contents.htm |
-+---------------------------------------------------------------+-----------------------------------------+
-
-CDROM is the directory where your CD-ROM is mounted, which is usually /mnt/
-cdrom/.
-
-InstallDir is the directory where you chose to install Adaptive Server
-Anywhere.
-
-The first two directories are put into the path by asa_config.sh or
-asa_config.csh, so if you've already executed one of them as mentioned in the
-previous section, you won't have to change directories to get to most of the
-executables associated with Adaptive Server Anywhere.
------------------------------------------------------------------------------
-
-4. Creating, Running and Connecting to Databases
-
-4.1. Creating a database
-
-When you ask Adaptive Server Anywhere to create a database, it creates the
-main database file, which contains the following objects, among others:
-
- * user tables
-
- * indexes
-
- * views
-
- * system tables
-
-
-The maximum size of a database file depends on your file system and the page
-size you choose. Database files are limited to 256 million database pages or
-the filesize limit, whichever is reached first. UNIX files can be as large as
-1 Tb, in some cases-see the Physical Limitations chapter of the Adaptive
-Server Anywhere Reference Manual or your Linux documentation for more
-information. You can set pages to be 1, 2, 4, 8, 16, or 32 kb in size, but it
-is not recommended that you use a page size of 1 kb. The default page size is
-2 kb.
-
-By default, Adaptive Server Anywhere also creates a file called the
-transaction log. Besides improving performance, the transaction log is vital
-to Adaptive Server Anywhere replication systems and database recovery in
-event of system failures. When possible, it is recommended that the
-transaction log be placed on a physical device (in most cases, a disk drive)
-separate from the main database file, to reduce the chances of both the main
-database file and transaction log being affected in the event of a media
-failure. You can specify the name and location of the transaction log when
-you create the database.
-
-This section shows you how to create databases at either the command prompt
-or in Interactive SQL. You can also create databases through Sybase Central,
-if you prefer, by opening the Utilities folder under Adaptive Server Anywhere
-7.
------------------------------------------------------------------------------
-
-4.1.1. Creating a database from the command prompt
-
-The command line utility for creating a database is dbinit.
-
-Syntax:
-
-dbinit [switches] db-file-name
-
-db-file-name is the name you would like to give to your database file, for
-example, mydb.db. If you issue the command "dbinit -?" you'll be shown the
-above syntax, along with a list of options you can use.
-
-To create your first Adaptive Server Anywhere database on Linux, enter the
-following command:
-
-dbinit -t './logs/mydb.log' p 4096 mydb.db
-
-This command creates a database in the current working directory called
-mydb.db with a page size of 4096 bytes, specified by the -p switch. Assuming
-the directory exists, it also creates the transaction log mydb.log in the
-subdirectory "logs," specified by the -t switch. Adaptive Server Anywhere
-databases carry the extension ".db" .
------------------------------------------------------------------------------
-
-4.1.2. Creating a database from Sybase Central
-
-To create a database in Sybase Central, open the Adaptive Server Anywhere
-section of the left pane, and select Utilities. Double-click Create Database
-in the right pane, and follow the on-screen instructions.
------------------------------------------------------------------------------
-
-4.2. Running a database server and starting databases
-
-There are two versions of the database server installed on your machine. If
-you are just using Adaptive Server Anywhere locally, use the personal
-database server (dbeng7). If you are going to connect to the Adaptive Server
-Anywhere database over a network, however, you should use the network
-database server (dbsrv7). Examples in this document use dbeng7, but the two
-commands are, for the most part, interchangeable. See the table below for
-specific differences.
-
-
-Table 7. Differences between the Personal and Network database servers
-+---------------------------------------------+-----------------------------+-----------------------------+
-| |Personal database server |Network database server |
-+---------------------------------------------+-----------------------------+-----------------------------+
-|Name of executable |dbeng7 |dbsrv7 |
-+---------------------------------------------+-----------------------------+-----------------------------+
-|Local connections |Yes |Yes |
-+---------------------------------------------+-----------------------------+-----------------------------+
-|Network connections |No |Yes |
-+---------------------------------------------+-----------------------------+-----------------------------+
-|Maximum number of connections |10 |Depends on license |
-+---------------------------------------------+-----------------------------+-----------------------------+
-|Available communications protocols |Shared memory, TCP/IP |Shared memory, TCP/IP |
-+---------------------------------------------+-----------------------------+-----------------------------+
-|Maximum number of CPUs for request processing|2 |Unlimited |
-+---------------------------------------------+-----------------------------+-----------------------------+
-|Default/Maximum number of internal threads |10/10 |20/Unlimited |
-+---------------------------------------------+-----------------------------+-----------------------------+
-
-Syntax:
-
-(dbeng7 | dbsrv7) [server-switches] [database-file [database-switches], ]
-
-database-file specifies the path and filename to the database. You aren't
-actually required to specify a database file when you start up the database
-server, but if you don't, you must specify a name for the server using the -n
-switch. By default, if you do not specify a name for the database, it takes
-on the name of the database file, minus the path and extension. Similarly, if
-you do not specify a name for the database server (which you can do in
-server-switches), it takes on the name of the first database that was started
-on it.
-
-For full details on the usage of dbeng7 and dbsrv7, see "The database server"
-in the Adaptive Server Anywhere Reference.
-
-To start up the Adaptive Server Anywhere personal database server, but not a
-database, and name it MyServer, issue the following command at a prompt:
-
-dbeng7 -n MyServer
-
-To start up the Adaptive Server Anywhere personal database server and name it
-MyServer, then start a database on MyServer from mydb.db, naming it
-MyDatabase, issue the following command:
-
-dbeng7 -n MyServer mydb.db -n MyDatabase
-
-In the latter case, if you don't name the database server MyServer, it would
-be named MyDatabase instead.
-
-There's a plethora of other switches available for the server. You can get a
-full listing of them by typing "dbeng7 -?" at a command prompt. A few
-important switches include the following:
-
- * -c, for specifying Adaptive Server Anywhere's cache size
-
- * -x allows you to specify the communications protocols
-
- * -gt allows you to specify the number of processors to be used
-
- * -ud tells the server to run as a daemon in UNIX (explained below)
-
-
------------------------------------------------------------------------------
-4.2.1. Running the server as a daemon
-
-Sometimes it's necessary for the server to run outside of the current session
-(that is, regardless of who, if anyone, is logged in). To do so, use the -ud
-switch at the command line when starting the server to run it as a daemon.
-
-The following command would start up a database server as a daemon, using the
-database we created before:
-
-dbsrv7 -ud -n MyDatabase mydb.db
-
-NOTE: Using "&" to run the database server in the background does not work.
------------------------------------------------------------------------------
-
-4.3. Stopping the database server
-
-Assuming you have the appropriate authority, you can stop the database server
-using any of the following methods:
-
- * the dbstop command line utility
-
- * using the STOP ENGINE SQL statement
-
- * pressing the Q key when the server display window has the focus
-
-
-NOTE: While the term engine is part of the SQL statement's name, server is
-the common term now used. This document will use the term server unless
-referring explicitly to the STOP ENGINE SQL statement.
-
-By default, any user can stop a personal database server, but only a user
-with the DBA authority can stop a network database server. (This default can
-be changed by using the -gk switch when starting the server-see the Adaptive
-Server Anywhere Reference for details.)
-
-The command line utility syntax is as follows:
-
-dbstop [switches] {name}
-
-If you are issuing dbstop to stop a locally-running server, you can simply
-specify the name of the database server in {name}. If the server is not
-running locally, you need to create a connection to the server before you can
-tell it to stop. The -c switch allows you to specify a connection string for
-the database running on the server that you would like to stop. To stop
-MyServer, execute the following command:
-
-dbstop -c "uid=DBA;pwd=SQL;eng=MyServer;dbn=MyDatabase"
-
-In this instance, you could also just give the server name, since the server
-is running locally:
-
-dbstop MyServer
-
-The first command connects to the database named MyDatabase on the server
-MyServer, then stops the server named MyServer. In the case that no databases
-are active on the server, you have to add "dbn=utility_db" to the connection
-string.
-
-Let's say "Club" is the name of one of the databases running on a server
-named "Goliath," and you want to stop all the databases running on Goliath,
-including Club. The following command accomplishes that, as well as shutting
-down the database server:
-
-dbstop -c "uid=DBA;pwd=SQL;eng=Goliath;dbn=Club"
-
-If you have a database server named "David" running without any databases
-started on it, you can stop the server using the following command:
-
-dbstop -c "uid=DBA;pwd=SQL;eng=David;dbn=utility_db"
-
-The syntax for the STOP ENGINE statement is as follows:
-
-STOP ENGINE [ server-name ] [ UNCONDITIONALLY ]
-
-The server named server-name is stopped. If server-name is omitted, the
-currently running database server is stopped. If UNCONDITIONALLY is
-specified, the database server is stopped whether or not there are still
-connections to the server.
------------------------------------------------------------------------------
-
-4.4. Stopping databases
-
-It's also possible to stop individual databases without stopping the server,
-or any of the other databases that might be running on it. To do so, use the
-STOP DATABASE SQL statement.
-
-Syntax:
-
-STOP DATABASE database-name [ON engine-name] [UNCONDITIONALLY]
-
-You specify the name of the database that you would like to stop in
-database-name, with the restriction that the database specified cannot be the
-currently connected one. The "ON engine-name" clause can be used only in
-Interactive SQL. You use it to specify the server that the database is
-running on. Outside of Interactive SQL, the database can only be stopped if
-it is on the current server. The UNCONDITIONALLY keyword forces databases to
-be stopped, even if there are connections to it. By default, you can't stop a
-database if there are connections active.
------------------------------------------------------------------------------
-
-4.5. Connecting to a database
-
-You can connect to an Adaptive Server Anywhere database via any of the
-following interfaces:
-
- * ODBC
-
- * OLE DB or ADO
-
- * Embedded SQL
-
- * Sybase Open Client
-
- * JDBC
-
-
-Regardless of how you connect, you must specify some parameters, such as a
-username and password, to establish a connection to the database. These can
-be specified in a connection string, the SQLCONNECT environment variable, an
-ODBC data source configuration, or the fields of a dialog box.
-
-In this section, you'll find explanations on how to connect via SQL and ODBC.
-
-As the Adaptive Server Anywhere network server is a client/server database,
-you may connect to a Linux-hosted database from Windows-based PCs and other
-non-Linux devices, as well as Linux applications. Programming interfaces such
-as OLE DB or ADO are available ony on Windows, but can still be used against
-a Linux-hosted database.
------------------------------------------------------------------------------
-
-4.5.1. Connection strings
-
-Connection strings are frequently used when performing actions on a database.
-They consist of a list of parameter settings, delimited by semicolons and
-enclosed in double quotes. There should be no extra spaces in a connection
-string.
-
-Example:
-
-"uid=DBA;pwd=SQL"
-
-The short strings of letters just before each equal sign (in this example,
-uid, pwd, and dbf) are called keywords, which each correspond to a connection
-parameter. There are many connection parameters available, and they are
-listed in the Connecting to a Database chapter of the Adaptive Server
-Anywhere User's Guide. They are also described in detail in the Connection
-and Communication Parameters chapter of the Adaptive Server Anywhere
-Reference.
-
-When Adaptive Server Anywhere utilities are looking for connection
-parameters, they check the SQLCONNECT environment variable for any parameters
-that were left out of the connection string. If you're putting connection
-parameters into the SQLCONNECT environment variable, replace the equal signs
-with number (#) signs. In bash you would use the following command:
-
-SQLCONNECT='uid#DBA;pwd#SQL'
-
-The single quotes are necessary in the above command because semicolons can
-be used to separate bash commands. You can also use double quotes.
-
-To make SQLCONNECT available in subsequent shells, you'd need to use "export
-SQLCONNECT" to export the SQLCONNECT variable to the environment. You may
-also want to put these commands into your .bash_profile (or .profile, if
-you're using another shell) if you want the same connection parameters to be
-available each time you log in.
------------------------------------------------------------------------------
-
-4.5.2. Connecting from Interactive SQL
-
-To connect to a database from Interactive SQL, go to the Command menu, and
-choose "Connect...", then fill in the dialog box as appropriate.
------------------------------------------------------------------------------
-
-4.5.3. Connecting via ODBC
-
-ODBC (which stands for Open Database Connectivity) is an industry-standard
-interface for connecting client applications to relational and non-relational
-DBMSes. When you create an ODBC data source, it encapsulates the data and any
-other information required to get the data, including connection parameters.
------------------------------------------------------------------------------
-
-4.5.3.1. Setting up ODBC with Adaptive Server Anywhere
-
-To connect to Adaptive Server Anywhere from ODBC applications on Linux, you
-can either use Sybase's ODBC driver as a driver manager, or use a third-party
-ODBC driver manager such as iODBC or unixODBC. If you choose the latter
-route, follow the installation instructions for the driver manager you've
-chosen and choose dbodbc7.so (which resides in the sybase/SYBSsa7/lib
-directory) as the ODBC driver for Adaptive Server Anywhere.
-
-If you choose the former route, you can use Adaptive Server Anywhere's ODBC
-driver as a driver manager if you will only be connecting to Adaptive Server
-Anywhere databases. To do so, you need to create a few symbolic links so that
-ODBC driver manager requests get routed to the Sybase ODBC driver. From the
-sybase/SYBSsa7/lib subdirectory, enter the following commands:
-
-$ ln -s dbodbc7.so libodbc.so
-
-$ ln -s dbodbc7.so libodbc.so.1
-
-$ ln -s dbodbc7.so libodbcinst.so
-
-$ ln -s dbodbc7.so libodbcinst.so.1
-
-That's it!
------------------------------------------------------------------------------
-
-4.5.3.2. About ODBC data sources
-
-Data sources exist on the client computer, with at least one for each
-database accessible via ODBC. They reside in the .odbc.ini file or in a
-separate .dsn file.
-
-If the client computer is running Linux or another UNIX operating system,
-ODBC data sources can be used both for ODBC applications as well as for the
-Interactive SQL and Sybase Central utilities.
-
-NOTE: The database server looks for .odbc.ini in the following locations,
-among several others:
-
- 1. ODBCINI environment variable
-
- 2. ODBCHOME and HOME environment variables
-
- 3. The user's home directory
-
- 4. The current directory
-
- 5. The path
-
- 6. The root directory
-
-
-If no .odbc.ini file exists in your home directory, you'll have to create one
-in your home directory. You can check if one exists by using the command "ls
--a ~/.odbc.ini".
-
-You manage ODBC data sources using the dbdsn command line utility.
-
-Syntax:
-dbdsn [ modifier-switches ]
- { -l
- | -d dsn
- | -g dsn
- | -w dsn [details-switches]
- | -cl }
-
-dbdsn has four main modes of operation, and its behaviour depends on whether
-you choose the -l, -d, -g, or -w switch. Where applicable, the name of the
-data source to be operated on is specified by dsn.
-
- * the -l switch lists the data sources that have been defined
-
- * the -d switch deletes the specified data source
-
- * the -g switch gives you the details of the specified data source
-
- * the -w switch creates a new DSN using parameters specified in
- details-switches
-
-
-The most important details-switch is the -c switch, which allows you to
-specify the usual database connection parameters. You can also specify the
-name of a database server as a details-switch. Type "dbdsn -cl" to display a
-list of available connection parameters.
-
-To create a new data source named MyNewDSN for the server MyServer, execute
-the following command at a shell prompt:
-
-dbdsn -w MyNewDSN -c "uid=dba;pwd=sql;eng=MyServer"
-
-If there is a data source named MyNewDSN already existing, dbdsn asks if you
-would like to overwrite it.
-
-Conversely, to delete MyNewDSN, execute the following command:
-
-dbdsn -d MyNewDSN
-
-The modifier-switches control how dbdsn outputs its messages to screen, and
-whether or not data sources can be overwritten without confirmation. For more
-information on other dbdsn options, see "The Data Source utility" under the
-Database Administration Utilities chapter of the Adaptive Server Anywhere
-Reference.
------------------------------------------------------------------------------
-
-4.5.3.3. Connecting to an ODBC data source
-
-Once you've created an ODBC data source, you can access it through the DSN
-(DataSourceName) connection string keyword.
-
-For an ODBC data source called mydatasrc, for example, use the following
-connection string to connect to the database associated with it:
-
-"dsn=mydatasrc"
-
-NOTE: Explicitly-provided connection parameters and SQLCONNECT override any
-parameters provided in the ODBC data source, in that order.
-
-NOTE: The FileDSN connection parameter is not yet available in version 7.0.2
-of Adaptive Server Anywhere. Future versions of Adaptive Server Anywhere
-should support File DSNs.
------------------------------------------------------------------------------
-
-5. Backing up and Restoring a Database
-
-Creating a backup of your data is a simple, essential component of any
-serious installation. Adaptive Server Anywhere includes utilities to help
-minimize data loss in case your data becomes corrupt as a result of media
-failure, power outage, or other failure.
------------------------------------------------------------------------------
-
-5.1. Creating a Backup of the Database
-
-Backups of Adaptive Server Anywhere databases can be performed through the
-dbbackup command line utility, SQL, or Sybase Central. Both full backups and
-incremental backups can be performed, and they can be performed either online
-or offline (that is, whether the server is running or not, respectively). In
-addition, backups can be performed both from the server side and from the
-client side.
------------------------------------------------------------------------------
-
-5.1.1. Full vs. Incremental Backups
-
-A full backup makes copies of the main database file and the transaction log
-file. While it's the most basic and essential type of backup, it usually
-isn't practical to regularly perform full backups of large databases. As a
-result, incremental backups are commonly used.
-
-An incremental backup makes a copy of the transaction log alone. It takes
-place as part of a cycle that begins with a full backup, which is then
-followed by a given number of incremental backups. Since only the transaction
-log is copied, an incremental backup uses less time and resources, making it
-particularly suited for large databases. Keep in mind, though, that the more
-time you leave between full backups, the greater the risk of losing data in
-the event that one of the transaction logs becomes unusable.
------------------------------------------------------------------------------
-
-5.1.2. Online vs. Offline Backups
-
-An online backup is performed without stopping the database server. It
-provides a consistent snapshot of the database, even as the database is
-modified. Online backups are useful for databases with high availability
-requirements, but they won't complete until all active transactions are
-complete.
-
-In contrast, offline backups are performed once the database server has been
-shut down. They're useful for when the database can be taken down on a
-regular basis. You make offline backups simply by copying the pertinent files
-to another location using the cp command in a terminal window.
-
-In either case, both full and incremental backups can be performed.
------------------------------------------------------------------------------
-
-5.1.3. Server-side vs. Client-side Backups
-
-An online backup can be performed from a client using the dbbackup command
-line utility. This is known as a client-side backup, and it puts a backup of
-the database on the client machine.
-
-An online backup can also be performed on the server by issuing the BACKUP
-statement in SQL. Server-side backups are generally faster, owing to the fact
-that client-side backups usually depend upon transport across networks.
------------------------------------------------------------------------------
-
-5.1.4. How to make a backup
-
-5.1.4.1. From the command line
-
-The command line utility for making a backup of your database is dbbackup.
-Its syntax is as follows:
-
-dbbackup [ switches ] directory
-
-directory specifies a destination directory for the backup files. Some useful
-switches include the following:
-
- * -c is used to specify a connection string to the database to be backed up
-
- * -d creates a backup of the main database file only
-
- * -t creates a backup of the transaction log only
-
- * -r renames any previous transaction log backups and creates a new one. It
- is necessary for replication systems.
-
- * -x deletes any previous transaction log backups and creates a new one. It
- should not be used in replication systems.
-
-
-For example, if you were creating your first backup, you would want to create
-a full backup of MyDatabase. To put it in ./backups, use the following
-command:
-
-dbbackup -c "uid=DBA;pwd=SQL;dbn=MyDatabase" ./backups
-
-The next few backups could be incremental backups, so use the following:
-
-dbbackup -t -r -c "uid=DBA;pwd=SQL;dbn=MyDatabase" ./backups
------------------------------------------------------------------------------
-
-5.1.4.2. From SQL
-
-If you prefer to back up your database from Interactive SQL, the SQL
-statement is BACKUP DATABASE. You must have DBA authority to use BACKUP
-DATABASE, whose syntax is as follows:
-BACKUP DATABASE DIRECTORY backup-directory
- [ WAIT BEFORE START ]
- [ DBFILE ONLY ]
- [ TRANSACTION LOG ONLY ]
- [ TRANSACTION LOG RENAME [ MATCH ] ]
- [ TRANSACTION LOG TRUNCATE ]
------------------------------------------------------------------------------
-
-5.1.4.3. From Sybase Central
-
-To make a backup from Sybase Central, open the Utilities folder under
-"Adaptive Server Anywhere 7" and double-click "Backup Database" to open a
-dialog box which will guide you through the backup process.
------------------------------------------------------------------------------
-
-5.2. Validating the database and its backup
-
-You should regularly use either Sybase Central, SQL, or the dbvalid command
-line utility to validate a backup of your database in read-only mode, and, if
-errors are found, make repairs against the original database. Never make
-changes to a backup database! To read more about validation, see "Validating
-a database" and "Validating a transaction log" under the Backup and Data
-Recovery chapter of the Adaptive Server Anywhere User's Guide.
------------------------------------------------------------------------------
-
-5.3. Recovering the database
-
-Depending on the way your database and its backups are set up, and the status
-of your files after a media failure, there are several possible processes
-involved in how you go about recovering data. For information on how to
-recover data in various situations, see the Backup and Data Recovery chapter
-of the Adaptive Server Anywhere User's Guide.
------------------------------------------------------------------------------
-
-6. Managing a Database
-
-6.1. Tables
-
-All data in relational databases is held in tables. Each column is assigned a
-data type, and each row of a table holds a value for each column. The
-following are true for any table in a relational database:
-
- * There is no significance to the order of rows and columns.
-
- * Each row contains exactly one value per column.
-
- * All values in a column are of the same type.
-
-
-Here are some things to keep in mind when designing your database:
-
- * give every table a primary key
-
- * make sure that each table holds information about one specific entity
-
- * foreign keys form the relationships between tables (and therefore
- entities)
-
-
------------------------------------------------------------------------------
-6.1.1. Creating a Table
-
-When you first create a database in Adaptive Server Anywhere, the only tables
-it contains are the system tables. To create tables to hold your data, use
-either the CREATE TABLE statement in SQL or the Sybase Central Table Editor.
-You must have the DBA or RESOURCE authority to create a table, and you must
-have the DBA authority make another user its owner.
-
-The CREATE TABLE statement has an extremely broad range of options that are
-documented in the Adaptive Server Anywhere Reference, so only a small subset
-of options are described here. The basic syntax is as follows:
-CREATE TABLE owner.table-name
- (column-name datatype [, column-name datatype]...)
-
-The "owner." portion before tablename is optional, and is used by a user with
-the DBA authority to make another user the owner of the new table. table-name
-and column-name, respectively, are the names of the table and its columns.
-Insert the words PRIMARY KEY after datatype to make it the primary key.
-
-See the SQL Data Types chapter of the Adaptive Server Anywhere Reference for
-a list of the types available and their characteristics.
-
-To create a table named customer with columns id, name, address,
-city_state_zip, and phone, with id as the primary key, for example, use the
-following CREATE TABLE statement:
-create table customer
- (id integer not null primary key,
- name char ( 35 ),
- address char ( 35 ),
- city_state_zip char ( 35 ),
- phone char ( 12 )
- )
-
-It's also important to add "not null" in the case of id, since it's the
-primary key.
-
-To create a table in Sybase Central, connect to your database and open its
-Tables folder. If you double-click "Add Table," Sybase Central Table Editor
-will be opened and using the button bar, you can set up the table as you
-wish. Hover the mouse pointer over each button to find out what it does.
-Don't forget to make a primary key before you close the Table Editor!
-
-Some table creation options documented in the Adaptive Server Anywhere
-Reference but not here that you might be interested in include automatic
-incrementation (often used on the primary key), constraints, and foreign
-keys.
------------------------------------------------------------------------------
-
-6.1.2. Making Alterations to Tables
-
-You can make many kinds of changes to a table once it's been created. Some of
-the things you can do include the following:
-
- * rename a table
-
- * add, remove, or rename columns
-
- * change the datatype, default value, or length of a column
-
-
-As with creating tables, you can alter them through SQL or Sybase Central. To
-alter a table in SQL, you use the ALTER TABLE statement. ALTER TABLE has a
-great variety of options, which are described in detail in the Adaptive
-Server Anywhere Reference. You'll see a few basic examples here just to get
-you started.
-
-To rename the customer table to cust:
-alter table customer
- rename cust
-
-To add a company_name column to cust, with a maximum length of 35 characters:
-alter table cust
- add (company_name char (35) )
-
-To give company_name a default value of "n/a" :
-alter table cust
- alter company_name set default 'n/a'
------------------------------------------------------------------------------
-
-6.2. Users, permissions, and authorities
-
-NOTE: Before putting an Adaptive Server Anywhere database into serious usage,
-your first order of business as the database administrator (DBA) should be to
-change the DBA password from the default password, "SQL." For details on how
-to do this, see section 6.2.5.
-
-This section describes the user IDs that are created for each database,
-briefly describes how to create new user IDs, and goes over some of the ways
-you can use user IDs to control outsiders access of data. For more
-information on user IDs, groups, and permissions, see the Managing User IDs
-and Permissions chapter of the Adaptive Server Anywhere User's Guide.
------------------------------------------------------------------------------
-
-6.2.1. User IDs
-
-6.2.1.1. Special user IDs
-
-When Adaptive Server Anywhere databases are initialized, two groups and two
-user IDs are created. The two groups created are SYS and PUBLIC. The two user
-IDs created are DBA and dbo.
-
-SYS is a user as well as a group, but no one can connect to the database
-using the user ID SYS. SYS owns the system tables and the system views, and
-only SYS can update the system tables.
-
-PUBLIC is a member of the SYS group, and has only SELECT permissions on most
-system tables and system views. Since new user IDs are, by default, members
-of PUBLIC, you should revoke PUBLIC's membership in SYS if you want new users
-to have no permissions by default.
-
-The DBA user can directly modify any part of an Adaptive Server Anywhere
-database except the system tables. This is why it's important to change the
-default DBA password from "SQL." You should be cautious when giving DBA
-authority to a user (see the DBA Authority section below). If a user needs
-DBA authority, s/he should be given DBA authority, rather than the DBA's
-password.
------------------------------------------------------------------------------
-
-6.2.1.2. Creating new user IDs
-
-The SQL statement to add a new user ID is GRANT CONNECT.
-
-Syntax:
-GRANT CONNECT TO userid1
- IDENTIFIED BY password1
-
-To add a user ID with the name Mortimer, execute the following SQL statement:
-grant connect to mortimer identified by
-monkey
------------------------------------------------------------------------------
-
-6.2.2. Permissions
-
-This section explains permissions on tables that can be granted to users.
-Permissions are granted on a user-by-user basis.
-
-There are a few different table permissions that can be granted to a user,
-and they are each granted separately.
-
- * SELECT allows the user to read data, and can be restricted to particular
- columns.
-
- * INSERT allows the user to add data.
-
- * UPDATE allows the user to change data, and can be restricted to
- particular columns.
-
- * DELETE allows the user to remove data.
-
- * ALTER allows the user to modify the structure of a table.
-
- * REFERENCES allows the user to add indexes, primary keys, and foreign
- keys.
-
- * ALL includes all the above permissions.
-
-
-With the exceptions of ALTER and REFERENCES, which apply to tables
-exclusively, the table permissions apply to both tables and views. The SQL
-syntax for granting permissions is as follows:
-GRANT [ SELECT (column-name, ...)
- | INSERT
- | UPDATE (column-name, ...)
- | DELETE
- | ALTER
- | REFERENCES
- | ALL ]
-ON table-name
-TO userid
-
-The user userid is given the specified permission(s) on the table identified
-by table-name. If the permissions granted include SELECT and/or UPDATE, they
-are granted only on the columns specified in column-name.
-
-Let's say a list of available banana types is stored in the type and quantity
-columns of a table named banana_supply. To allow Mortimer to see a list of
-available banana types along with their quantities, use the following SQL
-statement:
-
-grant select on banana_supply (type, quantity) to mortimer
-
-When you grant a permission to a user, you have the option of granting him
-the ability to grant that same permission to others. To grant a user the
-permission to do so, add WITH GRANT OPTION to the end of your users GRANT
-statement when you're granting them their permissions.
-
-To allow Mortimer to see a list of banana types available along with the
-quantities of each, as well as allowing him to grant others the same SELECT
-permission, use this SQL statement:
-grant select on banana_supply (type, quantity)
-to mortimer
- with grant option
------------------------------------------------------------------------------
-
-6.2.3. Authorities
-
-An authority is a different level of permission. There are two types of
-authority.
------------------------------------------------------------------------------
-
-6.2.3.1. RESOURCE authority
-
-A user with the RESOURCE authority can create and drop database objects such
-as tables, views, stored procedures, and functions. The RESOURCE authority
-also allows the user to create and remove user IDs and passwords. To give
-userid the RESOURCE authority, execute the following SQL statement:
-
-GRANT RESOURCE TO userid
------------------------------------------------------------------------------
-
-6.2.3.2. DBA authority
-
-A user with the DBA authority can perform any database operation, and
-automatically has all permissions on all tables, except the system tables.
-The DBA can create and remove user IDs and passwords, grant RESOURCE and DBA
-authority, and unload and reload the database.
-
-GRANT DBA TO userid
------------------------------------------------------------------------------
-
-6.2.4. Removing Users and Revoking Permissions
-
-The SQL statement to delete a user ID is REVOKE CONNECT.
-
-Syntax:
-
-REVOKE CONNECT FROM userid [, userid ]
-
-As suggested by the portions in square parentheses, it's possible to remove
-multiple user IDs in a single statement. For example, to remove the user IDs
-for Mortimer and Chestington, execute this statement:
-
-revoke connect from mortimer, chestington
-
-To revoke permissions or authorities given to a particular user, you take the
-original granting statement, replace the GRANT with REVOKE, and replace the
-TO with FROM. To take away Mortimer's permission to view the banana_supply
-table, for example, use this REVOKE statement:
-
-revoke select on banana_supply (type, quantity) from mortimer
------------------------------------------------------------------------------
-
-6.2.5. Changing Passwords
-
-To change the password associated with a particular user ID, use a GRANT
-CONNECT statement again:
-
-GRANT CONNECT TO userid IDENTIFIED BY newpassword
-
-For example, to change the DBA's password from "SQL" to "d0n13xw9," use this
-statement:
-
-grant connect to DBA identified by d0n13xw9
------------------------------------------------------------------------------
-
-6.3. Making the database more secure
-
-Some of the Adaptive Server Anywhere features you may wish to use in building
-a secure environment for your data include the following:
-
- * User identification and authentication control access to databases.
-
- * Permissions and authorities, which have already been explained in
- previous sections, control the actions a user can carry out while
- connected to a database.
-
- * Views and stored procedures allow you to carefully tune the data a user
- can access and the operations a user can execute.
-
- * Connection encryption can prevent unauthorized persons from snooping.
-
-
-Some of these features have already been mentioned in this HOWTO, and some of
-them will be elaborated upon in the following sections. While the concepts of
-triggers, procedures, and views will be introduced so you can decide if and
-how you'll use them, their implementation won't be discussed. You can find
-indepth information on them, as well as details on their implementation, in
-the sections of the Adaptive Server Anywhere User's Guide listed below:
-
-
-Table 8.
-+----------------------------------------+---------------------------------------------------------------+
-|Chapter |Section |
-+----------------------------------------+---------------------------------------------------------------+
-|Using Procedures, Triggers, and Batches |Benefits of procedures and triggers |
-+----------------------------------------+---------------------------------------------------------------+
-|Managing User IDs and Permissions |Using views and procedures for extra security |
-+----------------------------------------+---------------------------------------------------------------+
------------------------------------------------------------------------------
-
-6.3.1. Increasing password security
-
-By default, passwords can be any length. For greater security, you can
-enforce a minimum length on all new passwords, to make them more difficult to
-guess. You do this by setting the MIN_PASSWORD_LENGTH database option to a
-greater value. The following statement enforces a minimum password length of
-8 characters:
-
-set option public.min_password_length = 8
-
-Check the "Changing Passwords" section of this document to learn how to
-change a user's password, and don't forget to change the DBA's password!
------------------------------------------------------------------------------
-
-6.3.2. Views, procedures, and triggers
-
-Views are useful when it is appropriate to give a user access to just one
-portion of a table. The portion can be defined in terms of rows or in terms
-of columns. For example, you may wish to prevent a group of users from seeing
-the quantity column of the banana_supply table, or you may wish to limit a
-user to see information on a particular type of banana.
-
-While views restrict access based on the data, procedures and triggers
-restrict access based on the actions a user can take. Procedures and triggers
-store SQL statements in a database for use by all applications. They execute
-under the table permissions of the associated table's owner, regardless of
-the permissions of the user who either executes the procedure or fires the
-trigger.
-
-Procedures are invoked by a CALL statement, and can take values as well as
-return them. Unlike procedures, however, triggers are can neither take values
-nor return them, and are invoked by insertions, updates, or deletions in the
-table it is associated with. Permissions are not associated with triggers.
-They execute when the action defined to fire them is performed, regardless of
-the user.
-
-For strict security, you can prevent all access to the tables, and grant
-permission to users to execute certain stored procedures that carry out
-specific tasks. This approach strictly defines the manner in which the
-database can be modified.
------------------------------------------------------------------------------
-
-6.3.3. Encrypting client/server communications
-
-Encrypting client/server communications prevents third parties from reading
-messages being sent between the client and the server. It can be enabled from
-either the server side or the client side. To enable encryption from the
-server, use the -e option at server startup. For example, use the following
-command to start up the database server to accept encrypted connections to
-mydb.db over TCP/IP:
-
-dbsrv7 -e -x tcpip mydb.db
-
-To enable encryption from a particular client, use the ENC keyword in the
-connection string. For example, to encrypt a connection over TCP/IP to
-mydb.db, your connection string would appear as follows:
-
-"uid=mortimer;pwd=monkey;links=tcpip;eng=MyServer;dbf=mydb.db;enc=true"
-
-For more information about client/server communications encryption, look for
-the -e command-line option under "The database server" in the Adaptive Server
-Anywhere Reference Manual, and for "Encryption connection parameter" under
-"Connection parameters" .
------------------------------------------------------------------------------
-
-7. Where to get more information
-
-On-line help is available on your cdrom. If your computer is set up to mount
-the CD-ROM to /mnt/cdrom/ the help is located in /mnt/cdrom/help/
-contents.htm. Open it with Netscape Navigator, or any other web browser that
-supports tables. Style sheets support is recommended, but not necessary.
-
-A FAQ is available for the UNIX version of Adaptive Server Anywhere at [http:
-//www.sybase.com/detail/1,3693,1011965,00.html] http://www.sybase.com/detail/
-1,3693,1011965,00.html
-
-Check if there have been any bug fixes or updates posted at [http://
-downloads.sybase.com/swx/sdmain.stm] http://downloads.sybase.com/swx/
-sdmain.stm.
-
-Newsgroups can be read from the web or with a news reader. The newsgroups
-sybase.public.sqlanywhere.general and sybase.public.sqlanywhere.linux are
-most likely to be relevant. To view newsgroups on the web, visit [http://
-www.sybase.com/support/newsgroups] http://www.sybase.com/support/newsgroups.
-Be sure to search old threads for similar problems. It may already have been
-resolved.
------------------------------------------------------------------------------
-
-8. Legalities and Acknowledgements
-
-8.1. Copyright and Licenses
-
-Copyright (c) 2001 Sybase Inc.
-
-This manual may be reproduced in whole or in part, without fee, subject to
-the following restrictions:
-
- * The copyright notice above and this permission notice must be preserved
- complete on all complete or partial copies.
-
- * Any translation or derived work must be approved by the author in writing
- before distribution.
-
- * If you distribute this work in part, instructions for obtaining the
- complete version of this manual must be included, and a means for
- obtaining a complete version provided.
-
- * Small portions may be reproduced as illustrations for reviews or quotes
- in other works without this permission notice if proper citation is
- given. Exceptions to these rules may be granted for academic purposes:
- Use the contact information in the next section to ask. These
- restrictions are here to protect us as authors, not to restrict you as
- learners and educators. Any source code (aside from the DocBook this
- document was written in) in this document is placed under the GNU General
- Public License, available via anonymous FTP from the GNU archive.
-
-
-The preceding notice was borrowed and tweaked from the LDP Author Guide's
-copyright notice.
------------------------------------------------------------------------------
-
-8.2. Names and Contacts
-
-This document was initiated by Michael Moller and (mostly) written by Aylwin
-Lo with assistance from Michael Heal and Tom Slee. We work at Sybase.
-
-Since the author is a co-op student, the best way to contact someone
-regarding this document is by posting to the sybase.public.sqlanywhere.linux
-newsgroup, available on the forums.sybase.com news server.
------------------------------------------------------------------------------
-
-8.3. Acknowledgement
-
-Thanks to the folks at [http://www.commandprompt.com/] http://
-www.commandprompt.com/ for getting the text of this HOWTO into workable SGML
-for us.
-
-Sybase Adaptive Server Anywhere for Linux HOWTO
-
-Aylwin Lo
-
-Tom Slee
-
-Sybase Inc.
-
- Tom.Slee@sybase.com
-
-Revision History
-Revision 1.0 2001-04-26 Revised by: al
-First public release.
-
-
-This HOWTO guides you through the installation of SQL Anywhere Studio 7.0.2
-for Linux and the basic operation and administration of Adaptive Server
-Anywhere databases.
-
------------------------------------------------------------------------------
-Table of Contents
-1. Introduction
- 1.1. New versions of this document
- 1.2. Content and Audience
- 1.3. Adaptive Server Anywhere features
- 1.4. Quirks
- 1.4.1. Alt and Function keys
-
-
- 1.5. What's a Relational Database?
- 1.5.1. Definition
- 1.5.2. Example
- 1.5.3. Primary and Foreign Keys
-
-
-
-
-2. Requirements
- 2.1. System requirements
- 2.2. Supported distributions
-
-
-3. Installation
- 3.1. Process
- 3.2. Distribution-specific considerations (for TurboLinux and Caldera)
- 3.3. Setting the Environment Variables
- 3.4. Where did it get installed?
-
-
-4. Creating, Running and Connecting to Databases
- 4.1. Creating a database
- 4.1.1. Creating a database from the command prompt
- 4.1.2. Creating a database from Sybase Central
-
-
- 4.2. Running a database server and starting databases
- 4.2.1. Running the server as a daemon
-
-
- 4.3. Stopping the database server
- 4.4. Stopping databases
- 4.5. Connecting to a database
- 4.5.1. Connection strings
- 4.5.2. Connecting from Interactive SQL
- 4.5.3. Connecting via ODBC
- 4.5.3.1. Setting up ODBC with Adaptive Server Anywhere
- 4.5.3.2. About ODBC data sources
- 4.5.3.3. Connecting to an ODBC data source
-
-
-
-
-
-
-5. Backing up and Restoring a Database
- 5.1. Creating a Backup of the Database
- 5.1.1. Full vs. Incremental Backups
- 5.1.2. Online vs. Offline Backups
- 5.1.3. Server-side vs. Client-side Backups
- 5.1.4. How to make a backup
- 5.1.4.1. From the command line
- 5.1.4.2. From SQL
- 5.1.4.3. From Sybase Central
-
-
-
-
- 5.2. Validating the database and its backup
- 5.3. Recovering the database
-
-
-6. Managing a Database
- 6.1. Tables
- 6.1.1. Creating a Table
- 6.1.2. Making Alterations to Tables
-
-
- 6.2. Users, permissions, and authorities
- 6.2.1. User IDs
- 6.2.1.1. Special user IDs
- 6.2.1.2. Creating new user IDs
-
-
- 6.2.2. Permissions
- 6.2.3. Authorities
- 6.2.3.1. RESOURCE authority
- 6.2.3.2. DBA authority
-
-
- 6.2.4. Removing Users and Revoking Permissions
- 6.2.5. Changing Passwords
-
-
- 6.3. Making the database more secure
- 6.3.1. Increasing password security
- 6.3.2. Views, procedures, and triggers
- 6.3.3. Encrypting client/server communications
-
-
-
-
-7. Where to get more information
-8. Legalities and Acknowledgements
- 8.1. Copyright and Licenses
- 8.2. Names and Contacts
- 8.3. Acknowledgement
-
-
-
------------------------------------------------------------------------------
-1. Introduction
-
-This HOWTO guides you through the installation of SQL Anywhere Studio 7.0.2
-for Linux and the basic operation and administration of Adaptive Server
-Anywhere databases.
------------------------------------------------------------------------------
-
-1.1. New versions of this document
-
-The latest version of this document should always be available at the Linux
-Documentation project website ([http://www.linuxdoc.org/] http://
-www.linuxdoc.org/).
------------------------------------------------------------------------------
-
-1.2. Content and Audience
-
-Within this document, you will find a list of the supported Linux
-distributions ("Section 2"). It is intended for moderately experienced users
-of Linux or UNIX. Familiarity with relational database concepts is certainly
-useful, but not a requirement. "Section 1.5" contains a summary of relational
-database concepts.
------------------------------------------------------------------------------
-
-1.3. Adaptive Server Anywhere features
-
-Adaptive Server Anywhere (Adaptive Server Anywhere) is the full SQL
-relational database management system at the heart of SQL Anywhere Studio.
-Ideally suited for use as an embedded database, in mobile computing, or as a
-workgroup server, it includes the following among its features:
-
- * Economical hardware requirements
-
- * Designed to operate without administration
-
- * Designed for mobile computing and synchronization
-
- * Ease of use
-
- * High performance
-
- * Cross-platform solution
-
- * Standalone and network use
-
- * Industry standard interfaces
-
-
-Some of the more specific features include:
-
- * Stored procedures and triggers
-
- * Java support for logic and datatypes
-
-
-For further details about Adaptive Server Anywhere, please visit the
-following links:
-
- * [http://www.sybase.com/detail/1,3693,1002624,00.html] http://
- www.sybase.com/detail/1,3693,1002624,00.html is a datasheet on SQL
- Anywhere Studio. It includes some data on Adaptive Server Anywhere, which
- ships as a component of SQL Anywhere Studio.
-
- * [http://www.sybase.com/detail/1,3693,1009210,00.html] http://
- www.sybase.com/detail/1,3693,1009210,00.html has some information on the
- features and system requirements of SQL Anywhere Studio and points you to
- the download location for SQL Anywhere Studio for Linux 7.0.
-
-
------------------------------------------------------------------------------
-1.4. Quirks
-
-1.4.1. Alt and Function keys
-
-Sometimes the Alt keys or the F1-F10 keys may not function in the terminal
-where you are running Interactive SQL.
-
-To emulate the Alt key, press Ctrl-A. Then press whatever key was to be
-pressed with the Alt key. For example, instead of pressing Alt-F, you would
-press Ctrl-A, then F.
-
-To emulate the function keys, press Ctrl-F, followed by the number of the
-function key you wanted to press. For example, instead of pressing F9, you
-would press Ctrl-F, then 9. For F10, use the zero key.
------------------------------------------------------------------------------
-
-1.5. What's a Relational Database?
-
-If you are already familiar with relational databases, you can skip this
-section.
------------------------------------------------------------------------------
-
-1.5.1. Definition
-
-A relational database-management system (RDBMS) is a system for storing and
-retrieving data, in which the data is organized in tables. A relational
-database consists of a collection of tables that store interrelated data.
-
-If that doesn't quite make sense yet, read on.
------------------------------------------------------------------------------
-
-1.5.2. Example
-
-Suppose you have some software to keep track of sales orders, and each order
-is stored in the form of a table, called sales_order. It has information
-about the customer (for example, her name, address and phone number), the
-date of the order, and information about the sales representative (for
-example his name, department, and office phone number). Let's put all this
-into a table, with the data for a few orders:
-
-
-Table 1. The sales_order table
-+-----------+---------------+--------------------+------------+-----------+------------+----------+------------+
-|cust_name |cust_address |cust_city_state_zip |cust_phone |order_date |emp_name |emp_dept |emp_phone |
-+-----------+---------------+--------------------+------------+-----------+------------+----------+------------+
-|M. Devlin |3114 Pioneer |Rutherford, NJ 07070|2015558966 |19930316 |R. Overbey |Sales |5105557255 |
-| |Ave. | | | | | | |
-+-----------+---------------+--------------------+------------+-----------+------------+----------+------------+
-|M. Devlin |3114 Pioneer |Rutherford, NJ 07070|2015558966 |19940405 |M. Kelly |Sales |5085553769 |
-| |Ave. | | | | | | |
-+-----------+---------------+--------------------+------------+-----------+------------+----------+------------+
-|J. |2800 Park Ave. |Hull, PQ K1A 0H3 |8195559539 |19940326 |M.Garcia |Sales |7135553431 |
-|Gagliardo | | | | | | | |
-+-----------+---------------+--------------------+------------+-----------+------------+----------+------------+
-|E. Peros |50 Market St. |Rochester, NY 14624 |7165554275 |19930603 |P. Chin |Sales |4045552341 |
-+-----------+---------------+--------------------+------------+-----------+------------+----------+------------+
-|E. Peros |50 Market St. |Rochester, NY 14624 |7165554275 |19940127 |M.Garcia |Sales |7135553431 |
-+-----------+---------------+--------------------+------------+-----------+------------+----------+------------+
-|E. Peros |50 Market St. |Rochester, NY 14624 |7165554275 |19940520 |J. Klobucher|Sales |7135558627 |
-+-----------+---------------+--------------------+------------+-----------+------------+----------+------------+
-
-Everything appears nice and ordered, but there's a fair bit of redundancy. M.
-Devlin's name appears twice, along with his address and phone number. E.
-Peros' details appear three times. If you look carefully at the employee side
-of things, you'll notice that M. Garcia is repeated, as well.
-
-Wouldn't it be nice if you could separate that information and only store it
-once, rather than several times? In the long term, it would certainly save
-disk space and allow for greater flexibility. Since redundant data entry is
-minimized, it would also reduce the chances of erroneous data entering the
-database, increasing consistency. Well, we can see three different entities
-involved here: the customer, the order, and the employee. So let's take each
-of the individuals, put them into categories, and give them identification
-numbers so they can be referenced.
-
-
-Table 2. The customer table
-+-----+------------+----------------+------------------+------------+
-|id |name |address |city_state_zip |phone |
-+-----+------------+----------------+------------------+------------+
-|101 |M. Devlin |3114 Pioneer |Rutherford, NJ |2015558966 |
-| | |Ave. |07070 | |
-+-----+------------+----------------+------------------+------------+
-|109 |J. Gagliardo|2800 Park Ave. |Hull, PQ K1A 0H3 |8195559539 |
-+-----+------------+----------------+------------------+------------+
-|180 |E. Peros |50 Market St. |Rochester, NY |7165554275 |
-| | | |14624 | |
-+-----+------------+----------------+------------------+------------+
-
-
-Table 3. The employee table
-+-----+-------------+-------+------------+
-|id |name |dept |phone |
-+-----+-------------+-------+------------+
-|299 |R. Overbey |Sales |5105557255 |
-+-----+-------------+-------+------------+
-|902 |M. Kelly |Sales |5085553769 |
-+-----+-------------+-------+------------+
-|667 |M.Garcia |Sales |7135553431 |
-+-----+-------------+-------+------------+
-|129 |P. Chin |Sales |4045552341 |
-+-----+-------------+-------+------------+
-|467 |J. Klobucher |Sales |7135558627 |
-+-----+-------------+-------+------------+
-
-
-Table 4. The new sales_order table
-+------+--------+-----------+-------------+
-|id |cust_id |order_date |sales_rep_id |
-+------+--------+-----------+-------------+
-|2001 |101 |19930316 |299 |
-+------+--------+-----------+-------------+
-|2583 |101 |19940405 |902 |
-+------+--------+-----------+-------------+
-|2576 |109 |19940326 |667 |
-+------+--------+-----------+-------------+
-|2081 |180 |19930603 |129 |
-+------+--------+-----------+-------------+
-|2503 |180 |19940127 |667 |
-+------+--------+-----------+-------------+
-|2640 |180 |19940520 |467 |
-+------+--------+-----------+-------------+
-
-As you can see, each customer's information is stored only once, and the same
-goes for each employee. The sales_order table is a lot smaller, too. Each
-row, representing a sales order, refers to a cust_id and an emp_id.
-
-By looking up the customer corresponding to a cust_id (which is unique), one
-can find all the needed data on that customer, without having to repeat it in
-sales_order. In addition, an id column has been added. Its purpose will be
-explained in the next section.
-
-Why do this, you ask? By eliminating redundancy, this kind of structure
-reduces the opportunities for inconsistencies to seep in, in addition to
-lowering storage requirements. If you had to change E. Peros' address in the
-old sales_order table, you'd have to do it three times, which would take
-three times as long and give you three times as many chances to make an
-error. In the newer table, all you'd have to do is change her address once,
-in the customer table. Also, by carefully separating data, you make access
-control simpler.
-
-Finally, can you spot another redundancy? The employee table has "Sales" all
-the way down the dept column. For an organization with multiple departments,
-you'd want to add a department table and reference it from a dept_id column
-instead.
------------------------------------------------------------------------------
-
-1.5.3. Primary and Foreign Keys
-
-As described in the previous section, you can separate a table into
-interrelated tables. But how do you go about relating tables to each other?
-In relational databases, primary keys and foreign keys help you link tables
-together. Primary keys are columns that uniquely identify each row of a
-table, and foreign keys define the relationship between the rows of two
-separate tables. Proper use of primary and foreign keys will help you
-efficiently hold information without excessive redundancy.
-
-Every table should have a primary key to ensure that each row is uniquely
-identified. This often takes the form of an ID number being assigned to each
-row, as in the previous section's example. The id column forms the primary
-key.
-
-As long as you can guarantee the uniqueness of the data in a particular
-column, though, that column can be a primary key. For example, if you only
-want one entry per day to be put into a particular table, you could use the
-date as that table's primary key.
-
-Tables are related to one another by foreign keys. In the sales_order
-example, the cust_id and sales_rep columns would be called foreign keys to
-the customer and employee tables, respectively. For terminology's sake, you
-might want to know that in this case, the sales_order table is called the
-foreign or referencing table, while the customer and employee tables are
-called the primary or referenced tables.
------------------------------------------------------------------------------
-
-2. Requirements
-
-2.1. System requirements
-
-Adaptive Server Anywhere requires that you have the following installed on
-your system:
-
- * kernel 2.2.5-15 and up (2.2.x series)
-
- * glibc-2.1 or up
-
- * pthreads-0.8 or higher (included usually as part of glibc)
-
- * libstdc++-2-libc6.1
-
-
------------------------------------------------------------------------------
-2.2. Supported distributions
-
-At present, the following Linux distributions are supported:
-
- * Caldera 2.4
-
- * Red Hat 7.0, 6.2, 6.1 or 6.0
-
- * TurboLinux 6.1
-
- * SuSE 7.0, 6.4, 6.3 or 6.2
-
-
-NOTE: The glibc and gcc released with Red Hat Linux 7.0 require patches
-before you can use Adaptive Server Anywhere. You can find them at [http://
-www.redhat.com/support/errata/rh7-errata-bugfixes.html] http://www.redhat.com
-/support/errata/rh7-errata-bugfixes.html.
------------------------------------------------------------------------------
-
-3. Installation
-
-3.1. Process
-
- 1. Log on as root.
-
- 2. Place the CD-ROM into the CD-ROM drive.
-
- 3. Mount the CD-ROM. Usually, it gets mounted to /mnt/cdrom. If so, enter
- the following command:
-
- mount /mnt/cdrom
-
- 4. At a command prompt, change to the CD-ROM directory. If the CD-ROM was
- mounted to /mnt/cdrom/, use the following command:
-
- cd /mnt/cdrom
-
- 5. Start the setup script by entering the following command:
-
- ./setup
-
- 6. The setup script prompts you with information about installing SQL
- Anywhere Studio for UNIX. Enter any information you are prompted for, and
- press the Enter key to continue.
-
-
-By default, SQL Anywhere Studio is installed into a directory named SYBSsa7
-under /opt/sybase on Solaris, Linux, and HP-UX, and under /usr/lpp/sybase on
-AIX. You can specify another installation directory if you wish.
------------------------------------------------------------------------------
-
-3.2. Distribution-specific considerations (for TurboLinux and Caldera)
-
-After installation, you should follow these instructions if you are running
-either TurboLinux 6.0 or Caldera 2.2.
-
-For TurboLinux 6.0 only, change to directory /usr/lib and create a symbolic
-link using the following command.
-
-ln -s libstdc++-libc6.1-2.so.3 libstdc++-libc6.1-1.so.2
-
-For Caldera 2.2 only, change to directory /usr/lib and create a symbolic link
-using the following command.
-
-ln -s /usr/lib/libstdc++-2.9.0 /usr/lib/libstdc++-libc6.1-1.so.2
------------------------------------------------------------------------------
-
-3.3. Setting the Environment Variables
-
-Each user who uses the software must set the necessary environment variables
-for Adaptive Server Anywhere. To help you do that, the installation program
-puts two script files, asa_config.sh and asa_config.csh, in the directory /
-InstallDir/SYBSsa7/bin. InstallDir is the directory where you chose to
-install Adaptive Server Anywhere.
-
-Depending on which shell you're using, enter the appropriate command from
-InstallDir.
-
-
-Table 5.
-+---------------------------+-------------------------------------+
-|If you're using this |...use this command. |
-|shell... | |
-+---------------------------+-------------------------------------+
-|sh, ksh, bash |. ./SYBSsa7/bin/asa_config.sh |
-+---------------------------+-------------------------------------+
-|csh, tcsh |source ./SYBSsa7/bin/asa_config.csh |
-+---------------------------+-------------------------------------+
-
-You may also want to insert the above commands into your copy of .profile or
-.bash_profile to have the environment variables ready every time you log in.
------------------------------------------------------------------------------
-
-3.4. Where did it get installed?
-
-Table 6.
-+---------------------------------------------------------------+-----------------------------------------+
-|Most Adaptive Server Anywhere command line utilities (names |/InstallDir/SYBSsa7/bin |
-|beginning with db) | |
-+---------------------------------------------------------------+-----------------------------------------+
-|Sybase Central |/InstallDir/shared/sybcentral40/java |
-+---------------------------------------------------------------+-----------------------------------------+
-|Sample database |/InstallDir/SYBSsa7 |
-+---------------------------------------------------------------+-----------------------------------------+
-|Online documentation |/CDROM/help/contents.htm or/InstallDir/ |
-| |SYBSsa7/doc/contents.htm |
-+---------------------------------------------------------------+-----------------------------------------+
-
-CDROM is the directory where your CD-ROM is mounted, which is usually /mnt/
-cdrom/.
-
-InstallDir is the directory where you chose to install Adaptive Server
-Anywhere.
-
-The first two directories are put into the path by asa_config.sh or
-asa_config.csh, so if you've already executed one of them as mentioned in the
-previous section, you won't have to change directories to get to most of the
-executables associated with Adaptive Server Anywhere.
------------------------------------------------------------------------------
-
-4. Creating, Running and Connecting to Databases
-
-4.1. Creating a database
-
-When you ask Adaptive Server Anywhere to create a database, it creates the
-main database file, which contains the following objects, among others:
-
- * user tables
-
- * indexes
-
- * views
-
- * system tables
-
-
-The maximum size of a database file depends on your file system and the page
-size you choose. Database files are limited to 256 million database pages or
-the filesize limit, whichever is reached first. UNIX files can be as large as
-1 Tb, in some cases-see the Physical Limitations chapter of the Adaptive
-Server Anywhere Reference Manual or your Linux documentation for more
-information. You can set pages to be 1, 2, 4, 8, 16, or 32 kb in size, but it
-is not recommended that you use a page size of 1 kb. The default page size is
-2 kb.
-
-By default, Adaptive Server Anywhere also creates a file called the
-transaction log. Besides improving performance, the transaction log is vital
-to Adaptive Server Anywhere replication systems and database recovery in
-event of system failures. When possible, it is recommended that the
-transaction log be placed on a physical device (in most cases, a disk drive)
-separate from the main database file, to reduce the chances of both the main
-database file and transaction log being affected in the event of a media
-failure. You can specify the name and location of the transaction log when
-you create the database.
-
-This section shows you how to create databases at either the command prompt
-or in Interactive SQL. You can also create databases through Sybase Central,
-if you prefer, by opening the Utilities folder under Adaptive Server Anywhere
-7.
------------------------------------------------------------------------------
-
-4.1.1. Creating a database from the command prompt
-
-The command line utility for creating a database is dbinit.
-
-Syntax:
-
-dbinit [switches] db-file-name
-
-db-file-name is the name you would like to give to your database file, for
-example, mydb.db. If you issue the command "dbinit -?" you'll be shown the
-above syntax, along with a list of options you can use.
-
-To create your first Adaptive Server Anywhere database on Linux, enter the
-following command:
-
-dbinit -t './logs/mydb.log' p 4096 mydb.db
-
-This command creates a database in the current working directory called
-mydb.db with a page size of 4096 bytes, specified by the -p switch. Assuming
-the directory exists, it also creates the transaction log mydb.log in the
-subdirectory "logs," specified by the -t switch. Adaptive Server Anywhere
-databases carry the extension ".db" .
------------------------------------------------------------------------------
-
-4.1.2. Creating a database from Sybase Central
-
-To create a database in Sybase Central, open the Adaptive Server Anywhere
-section of the left pane, and select Utilities. Double-click Create Database
-in the right pane, and follow the on-screen instructions.
------------------------------------------------------------------------------
-
-4.2. Running a database server and starting databases
-
-There are two versions of the database server installed on your machine. If
-you are just using Adaptive Server Anywhere locally, use the personal
-database server (dbeng7). If you are going to connect to the Adaptive Server
-Anywhere database over a network, however, you should use the network
-database server (dbsrv7). Examples in this document use dbeng7, but the two
-commands are, for the most part, interchangeable. See the table below for
-specific differences.
-
-
-Table 7. Differences between the Personal and Network database servers
-+---------------------------------------------+-----------------------------+-----------------------------+
-| |Personal database server |Network database server |
-+---------------------------------------------+-----------------------------+-----------------------------+
-|Name of executable |dbeng7 |dbsrv7 |
-+---------------------------------------------+-----------------------------+-----------------------------+
-|Local connections |Yes |Yes |
-+---------------------------------------------+-----------------------------+-----------------------------+
-|Network connections |No |Yes |
-+---------------------------------------------+-----------------------------+-----------------------------+
-|Maximum number of connections |10 |Depends on license |
-+---------------------------------------------+-----------------------------+-----------------------------+
-|Available communications protocols |Shared memory, TCP/IP |Shared memory, TCP/IP |
-+---------------------------------------------+-----------------------------+-----------------------------+
-|Maximum number of CPUs for request processing|2 |Unlimited |
-+---------------------------------------------+-----------------------------+-----------------------------+
-|Default/Maximum number of internal threads |10/10 |20/Unlimited |
-+---------------------------------------------+-----------------------------+-----------------------------+
-
-Syntax:
-
-(dbeng7 | dbsrv7) [server-switches] [database-file [database-switches], ]
-
-database-file specifies the path and filename to the database. You aren't
-actually required to specify a database file when you start up the database
-server, but if you don't, you must specify a name for the server using the -n
-switch. By default, if you do not specify a name for the database, it takes
-on the name of the database file, minus the path and extension. Similarly, if
-you do not specify a name for the database server (which you can do in
-server-switches), it takes on the name of the first database that was started
-on it.
-
-For full details on the usage of dbeng7 and dbsrv7, see "The database server"
-in the Adaptive Server Anywhere Reference.
-
-To start up the Adaptive Server Anywhere personal database server, but not a
-database, and name it MyServer, issue the following command at a prompt:
-
-dbeng7 -n MyServer
-
-To start up the Adaptive Server Anywhere personal database server and name it
-MyServer, then start a database on MyServer from mydb.db, naming it
-MyDatabase, issue the following command:
-
-dbeng7 -n MyServer mydb.db -n MyDatabase
-
-In the latter case, if you don't name the database server MyServer, it would
-be named MyDatabase instead.
-
-There's a plethora of other switches available for the server. You can get a
-full listing of them by typing "dbeng7 -?" at a command prompt. A few
-important switches include the following:
-
- * -c, for specifying Adaptive Server Anywhere's cache size
-
- * -x allows you to specify the communications protocols
-
- * -gt allows you to specify the number of processors to be used
-
- * -ud tells the server to run as a daemon in UNIX (explained below)
-
-
------------------------------------------------------------------------------
-4.2.1. Running the server as a daemon
-
-Sometimes it's necessary for the server to run outside of the current session
-(that is, regardless of who, if anyone, is logged in). To do so, use the -ud
-switch at the command line when starting the server to run it as a daemon.
-
-The following command would start up a database server as a daemon, using the
-database we created before:
-
-dbsrv7 -ud -n MyDatabase mydb.db
-
-NOTE: Using "&" to run the database server in the background does not work.
------------------------------------------------------------------------------
-
-4.3. Stopping the database server
-
-Assuming you have the appropriate authority, you can stop the database server
-using any of the following methods:
-
- * the dbstop command line utility
-
- * using the STOP ENGINE SQL statement
-
- * pressing the Q key when the server display window has the focus
-
-
-NOTE: While the term engine is part of the SQL statement's name, server is
-the common term now used. This document will use the term server unless
-referring explicitly to the STOP ENGINE SQL statement.
-
-By default, any user can stop a personal database server, but only a user
-with the DBA authority can stop a network database server. (This default can
-be changed by using the -gk switch when starting the server-see the Adaptive
-Server Anywhere Reference for details.)
-
-The command line utility syntax is as follows:
-
-dbstop [switches] {name}
-
-If you are issuing dbstop to stop a locally-running server, you can simply
-specify the name of the database server in {name}. If the server is not
-running locally, you need to create a connection to the server before you can
-tell it to stop. The -c switch allows you to specify a connection string for
-the database running on the server that you would like to stop. To stop
-MyServer, execute the following command:
-
-dbstop -c "uid=DBA;pwd=SQL;eng=MyServer;dbn=MyDatabase"
-
-In this instance, you could also just give the server name, since the server
-is running locally:
-
-dbstop MyServer
-
-The first command connects to the database named MyDatabase on the server
-MyServer, then stops the server named MyServer. In the case that no databases
-are active on the server, you have to add "dbn=utility_db" to the connection
-string.
-
-Let's say "Club" is the name of one of the databases running on a server
-named "Goliath," and you want to stop all the databases running on Goliath,
-including Club. The following command accomplishes that, as well as shutting
-down the database server:
-
-dbstop -c "uid=DBA;pwd=SQL;eng=Goliath;dbn=Club"
-
-If you have a database server named "David" running without any databases
-started on it, you can stop the server using the following command:
-
-dbstop -c "uid=DBA;pwd=SQL;eng=David;dbn=utility_db"
-
-The syntax for the STOP ENGINE statement is as follows:
-
-STOP ENGINE [ server-name ] [ UNCONDITIONALLY ]
-
-The server named server-name is stopped. If server-name is omitted, the
-currently running database server is stopped. If UNCONDITIONALLY is
-specified, the database server is stopped whether or not there are still
-connections to the server.
------------------------------------------------------------------------------
-
-4.4. Stopping databases
-
-It's also possible to stop individual databases without stopping the server,
-or any of the other databases that might be running on it. To do so, use the
-STOP DATABASE SQL statement.
-
-Syntax:
-
-STOP DATABASE database-name [ON engine-name] [UNCONDITIONALLY]
-
-You specify the name of the database that you would like to stop in
-database-name, with the restriction that the database specified cannot be the
-currently connected one. The "ON engine-name" clause can be used only in
-Interactive SQL. You use it to specify the server that the database is
-running on. Outside of Interactive SQL, the database can only be stopped if
-it is on the current server. The UNCONDITIONALLY keyword forces databases to
-be stopped, even if there are connections to it. By default, you can't stop a
-database if there are connections active.
------------------------------------------------------------------------------
-
-4.5. Connecting to a database
-
-You can connect to an Adaptive Server Anywhere database via any of the
-following interfaces:
-
- * ODBC
-
- * OLE DB or ADO
-
- * Embedded SQL
-
- * Sybase Open Client
-
- * JDBC
-
-
-Regardless of how you connect, you must specify some parameters, such as a
-username and password, to establish a connection to the database. These can
-be specified in a connection string, the SQLCONNECT environment variable, an
-ODBC data source configuration, or the fields of a dialog box.
-
-In this section, you'll find explanations on how to connect via SQL and ODBC.
-
-As the Adaptive Server Anywhere network server is a client/server database,
-you may connect to a Linux-hosted database from Windows-based PCs and other
-non-Linux devices, as well as Linux applications. Programming interfaces such
-as OLE DB or ADO are available ony on Windows, but can still be used against
-a Linux-hosted database.
------------------------------------------------------------------------------
-
-4.5.1. Connection strings
-
-Connection strings are frequently used when performing actions on a database.
-They consist of a list of parameter settings, delimited by semicolons and
-enclosed in double quotes. There should be no extra spaces in a connection
-string.
-
-Example:
-
-"uid=DBA;pwd=SQL"
-
-The short strings of letters just before each equal sign (in this example,
-uid, pwd, and dbf) are called keywords, which each correspond to a connection
-parameter. There are many connection parameters available, and they are
-listed in the Connecting to a Database chapter of the Adaptive Server
-Anywhere User's Guide. They are also described in detail in the Connection
-and Communication Parameters chapter of the Adaptive Server Anywhere
-Reference.
-
-When Adaptive Server Anywhere utilities are looking for connection
-parameters, they check the SQLCONNECT environment variable for any parameters
-that were left out of the connection string. If you're putting connection
-parameters into the SQLCONNECT environment variable, replace the equal signs
-with number (#) signs. In bash you would use the following command:
-
-SQLCONNECT='uid#DBA;pwd#SQL'
-
-The single quotes are necessary in the above command because semicolons can
-be used to separate bash commands. You can also use double quotes.
-
-To make SQLCONNECT available in subsequent shells, you'd need to use "export
-SQLCONNECT" to export the SQLCONNECT variable to the environment. You may
-also want to put these commands into your .bash_profile (or .profile, if
-you're using another shell) if you want the same connection parameters to be
-available each time you log in.
------------------------------------------------------------------------------
-
-4.5.2. Connecting from Interactive SQL
-
-To connect to a database from Interactive SQL, go to the Command menu, and
-choose "Connect...", then fill in the dialog box as appropriate.
------------------------------------------------------------------------------
-
-4.5.3. Connecting via ODBC
-
-ODBC (which stands for Open Database Connectivity) is an industry-standard
-interface for connecting client applications to relational and non-relational
-DBMSes. When you create an ODBC data source, it encapsulates the data and any
-other information required to get the data, including connection parameters.
------------------------------------------------------------------------------
-
-4.5.3.1. Setting up ODBC with Adaptive Server Anywhere
-
-To connect to Adaptive Server Anywhere from ODBC applications on Linux, you
-can either use Sybase's ODBC driver as a driver manager, or use a third-party
-ODBC driver manager such as iODBC or unixODBC. If you choose the latter
-route, follow the installation instructions for the driver manager you've
-chosen and choose dbodbc7.so (which resides in the sybase/SYBSsa7/lib
-directory) as the ODBC driver for Adaptive Server Anywhere.
-
-If you choose the former route, you can use Adaptive Server Anywhere's ODBC
-driver as a driver manager if you will only be connecting to Adaptive Server
-Anywhere databases. To do so, you need to create a few symbolic links so that
-ODBC driver manager requests get routed to the Sybase ODBC driver. From the
-sybase/SYBSsa7/lib subdirectory, enter the following commands:
-
-$ ln -s dbodbc7.so libodbc.so
-
-$ ln -s dbodbc7.so libodbc.so.1
-
-$ ln -s dbodbc7.so libodbcinst.so
-
-$ ln -s dbodbc7.so libodbcinst.so.1
-
-That's it!
------------------------------------------------------------------------------
-
-4.5.3.2. About ODBC data sources
-
-Data sources exist on the client computer, with at least one for each
-database accessible via ODBC. They reside in the .odbc.ini file or in a
-separate .dsn file.
-
-If the client computer is running Linux or another UNIX operating system,
-ODBC data sources can be used both for ODBC applications as well as for the
-Interactive SQL and Sybase Central utilities.
-
-NOTE: The database server looks for .odbc.ini in the following locations,
-among several others:
-
- 1. ODBCINI environment variable
-
- 2. ODBCHOME and HOME environment variables
-
- 3. The user's home directory
-
- 4. The current directory
-
- 5. The path
-
- 6. The root directory
-
-
-If no .odbc.ini file exists in your home directory, you'll have to create one
-in your home directory. You can check if one exists by using the command "ls
--a ~/.odbc.ini".
-
-You manage ODBC data sources using the dbdsn command line utility.
-
-Syntax:
-dbdsn [ modifier-switches ]
- { -l
- | -d dsn
- | -g dsn
- | -w dsn [details-switches]
- | -cl }
-
-dbdsn has four main modes of operation, and its behaviour depends on whether
-you choose the -l, -d, -g, or -w switch. Where applicable, the name of the
-data source to be operated on is specified by dsn.
-
- * the -l switch lists the data sources that have been defined
-
- * the -d switch deletes the specified data source
-
- * the -g switch gives you the details of the specified data source
-
- * the -w switch creates a new DSN using parameters specified in
- details-switches
-
-
-The most important details-switch is the -c switch, which allows you to
-specify the usual database connection parameters. You can also specify the
-name of a database server as a details-switch. Type "dbdsn -cl" to display a
-list of available connection parameters.
-
-To create a new data source named MyNewDSN for the server MyServer, execute
-the following command at a shell prompt:
-
-dbdsn -w MyNewDSN -c "uid=dba;pwd=sql;eng=MyServer"
-
-If there is a data source named MyNewDSN already existing, dbdsn asks if you
-would like to overwrite it.
-
-Conversely, to delete MyNewDSN, execute the following command:
-
-dbdsn -d MyNewDSN
-
-The modifier-switches control how dbdsn outputs its messages to screen, and
-whether or not data sources can be overwritten without confirmation. For more
-information on other dbdsn options, see "The Data Source utility" under the
-Database Administration Utilities chapter of the Adaptive Server Anywhere
-Reference.
------------------------------------------------------------------------------
-
-4.5.3.3. Connecting to an ODBC data source
-
-Once you've created an ODBC data source, you can access it through the DSN
-(DataSourceName) connection string keyword.
-
-For an ODBC data source called mydatasrc, for example, use the following
-connection string to connect to the database associated with it:
-
-"dsn=mydatasrc"
-
-NOTE: Explicitly-provided connection parameters and SQLCONNECT override any
-parameters provided in the ODBC data source, in that order.
-
-NOTE: The FileDSN connection parameter is not yet available in version 7.0.2
-of Adaptive Server Anywhere. Future versions of Adaptive Server Anywhere
-should support File DSNs.
------------------------------------------------------------------------------
-
-5. Backing up and Restoring a Database
-
-Creating a backup of your data is a simple, essential component of any
-serious installation. Adaptive Server Anywhere includes utilities to help
-minimize data loss in case your data becomes corrupt as a result of media
-failure, power outage, or other failure.
------------------------------------------------------------------------------
-
-5.1. Creating a Backup of the Database
-
-Backups of Adaptive Server Anywhere databases can be performed through the
-dbbackup command line utility, SQL, or Sybase Central. Both full backups and
-incremental backups can be performed, and they can be performed either online
-or offline (that is, whether the server is running or not, respectively). In
-addition, backups can be performed both from the server side and from the
-client side.
------------------------------------------------------------------------------
-
-5.1.1. Full vs. Incremental Backups
-
-A full backup makes copies of the main database file and the transaction log
-file. While it's the most basic and essential type of backup, it usually
-isn't practical to regularly perform full backups of large databases. As a
-result, incremental backups are commonly used.
-
-An incremental backup makes a copy of the transaction log alone. It takes
-place as part of a cycle that begins with a full backup, which is then
-followed by a given number of incremental backups. Since only the transaction
-log is copied, an incremental backup uses less time and resources, making it
-particularly suited for large databases. Keep in mind, though, that the more
-time you leave between full backups, the greater the risk of losing data in
-the event that one of the transaction logs becomes unusable.
------------------------------------------------------------------------------
-
-5.1.2. Online vs. Offline Backups
-
-An online backup is performed without stopping the database server. It
-provides a consistent snapshot of the database, even as the database is
-modified. Online backups are useful for databases with high availability
-requirements, but they won't complete until all active transactions are
-complete.
-
-In contrast, offline backups are performed once the database server has been
-shut down. They're useful for when the database can be taken down on a
-regular basis. You make offline backups simply by copying the pertinent files
-to another location using the cp command in a terminal window.
-
-In either case, both full and incremental backups can be performed.
------------------------------------------------------------------------------
-
-5.1.3. Server-side vs. Client-side Backups
-
-An online backup can be performed from a client using the dbbackup command
-line utility. This is known as a client-side backup, and it puts a backup of
-the database on the client machine.
-
-An online backup can also be performed on the server by issuing the BACKUP
-statement in SQL. Server-side backups are generally faster, owing to the fact
-that client-side backups usually depend upon transport across networks.
------------------------------------------------------------------------------
-
-5.1.4. How to make a backup
-
-5.1.4.1. From the command line
-
-The command line utility for making a backup of your database is dbbackup.
-Its syntax is as follows:
-
-dbbackup [ switches ] directory
-
-directory specifies a destination directory for the backup files. Some useful
-switches include the following:
-
- * -c is used to specify a connection string to the database to be backed up
-
- * -d creates a backup of the main database file only
-
- * -t creates a backup of the transaction log only
-
- * -r renames any previous transaction log backups and creates a new one. It
- is necessary for replication systems.
-
- * -x deletes any previous transaction log backups and creates a new one. It
- should not be used in replication systems.
-
-
-For example, if you were creating your first backup, you would want to create
-a full backup of MyDatabase. To put it in ./backups, use the following
-command:
-
-dbbackup -c "uid=DBA;pwd=SQL;dbn=MyDatabase" ./backups
-
-The next few backups could be incremental backups, so use the following:
-
-dbbackup -t -r -c "uid=DBA;pwd=SQL;dbn=MyDatabase" ./backups
------------------------------------------------------------------------------
-
-5.1.4.2. From SQL
-
-If you prefer to back up your database from Interactive SQL, the SQL
-statement is BACKUP DATABASE. You must have DBA authority to use BACKUP
-DATABASE, whose syntax is as follows:
-BACKUP DATABASE DIRECTORY backup-directory
- [ WAIT BEFORE START ]
- [ DBFILE ONLY ]
- [ TRANSACTION LOG ONLY ]
- [ TRANSACTION LOG RENAME [ MATCH ] ]
- [ TRANSACTION LOG TRUNCATE ]
------------------------------------------------------------------------------
-
-5.1.4.3. From Sybase Central
-
-To make a backup from Sybase Central, open the Utilities folder under
-"Adaptive Server Anywhere 7" and double-click "Backup Database" to open a
-dialog box which will guide you through the backup process.
------------------------------------------------------------------------------
-
-5.2. Validating the database and its backup
-
-You should regularly use either Sybase Central, SQL, or the dbvalid command
-line utility to validate a backup of your database in read-only mode, and, if
-errors are found, make repairs against the original database. Never make
-changes to a backup database! To read more about validation, see "Validating
-a database" and "Validating a transaction log" under the Backup and Data
-Recovery chapter of the Adaptive Server Anywhere User's Guide.
------------------------------------------------------------------------------
-
-5.3. Recovering the database
-
-Depending on the way your database and its backups are set up, and the status
-of your files after a media failure, there are several possible processes
-involved in how you go about recovering data. For information on how to
-recover data in various situations, see the Backup and Data Recovery chapter
-of the Adaptive Server Anywhere User's Guide.
------------------------------------------------------------------------------
-
-6. Managing a Database
-
-6.1. Tables
-
-All data in relational databases is held in tables. Each column is assigned a
-data type, and each row of a table holds a value for each column. The
-following are true for any table in a relational database:
-
- * There is no significance to the order of rows and columns.
-
- * Each row contains exactly one value per column.
-
- * All values in a column are of the same type.
-
-
-Here are some things to keep in mind when designing your database:
-
- * give every table a primary key
-
- * make sure that each table holds information about one specific entity
-
- * foreign keys form the relationships between tables (and therefore
- entities)
-
-
------------------------------------------------------------------------------
-6.1.1. Creating a Table
-
-When you first create a database in Adaptive Server Anywhere, the only tables
-it contains are the system tables. To create tables to hold your data, use
-either the CREATE TABLE statement in SQL or the Sybase Central Table Editor.
-You must have the DBA or RESOURCE authority to create a table, and you must
-have the DBA authority make another user its owner.
-
-The CREATE TABLE statement has an extremely broad range of options that are
-documented in the Adaptive Server Anywhere Reference, so only a small subset
-of options are described here. The basic syntax is as follows:
-CREATE TABLE owner.table-name
- (column-name datatype [, column-name datatype]...)
-
-The "owner." portion before tablename is optional, and is used by a user with
-the DBA authority to make another user the owner of the new table. table-name
-and column-name, respectively, are the names of the table and its columns.
-Insert the words PRIMARY KEY after datatype to make it the primary key.
-
-See the SQL Data Types chapter of the Adaptive Server Anywhere Reference for
-a list of the types available and their characteristics.
-
-To create a table named customer with columns id, name, address,
-city_state_zip, and phone, with id as the primary key, for example, use the
-following CREATE TABLE statement:
-create table customer
- (id integer not null primary key,
- name char ( 35 ),
- address char ( 35 ),
- city_state_zip char ( 35 ),
- phone char ( 12 )
- )
-
-It's also important to add "not null" in the case of id, since it's the
-primary key.
-
-To create a table in Sybase Central, connect to your database and open its
-Tables folder. If you double-click "Add Table," Sybase Central Table Editor
-will be opened and using the button bar, you can set up the table as you
-wish. Hover the mouse pointer over each button to find out what it does.
-Don't forget to make a primary key before you close the Table Editor!
-
-Some table creation options documented in the Adaptive Server Anywhere
-Reference but not here that you might be interested in include automatic
-incrementation (often used on the primary key), constraints, and foreign
-keys.
------------------------------------------------------------------------------
-
-6.1.2. Making Alterations to Tables
-
-You can make many kinds of changes to a table once it's been created. Some of
-the things you can do include the following:
-
- * rename a table
-
- * add, remove, or rename columns
-
- * change the datatype, default value, or length of a column
-
-
-As with creating tables, you can alter them through SQL or Sybase Central. To
-alter a table in SQL, you use the ALTER TABLE statement. ALTER TABLE has a
-great variety of options, which are described in detail in the Adaptive
-Server Anywhere Reference. You'll see a few basic examples here just to get
-you started.
-
-To rename the customer table to cust:
-alter table customer
- rename cust
-
-To add a company_name column to cust, with a maximum length of 35 characters:
-alter table cust
- add (company_name char (35) )
-
-To give company_name a default value of "n/a" :
-alter table cust
- alter company_name set default 'n/a'
------------------------------------------------------------------------------
-
-6.2. Users, permissions, and authorities
-
-NOTE: Before putting an Adaptive Server Anywhere database into serious usage,
-your first order of business as the database administrator (DBA) should be to
-change the DBA password from the default password, "SQL." For details on how
-to do this, see section 6.2.5.
-
-This section describes the user IDs that are created for each database,
-briefly describes how to create new user IDs, and goes over some of the ways
-you can use user IDs to control outsiders access of data. For more
-information on user IDs, groups, and permissions, see the Managing User IDs
-and Permissions chapter of the Adaptive Server Anywhere User's Guide.
------------------------------------------------------------------------------
-
-6.2.1. User IDs
-
-6.2.1.1. Special user IDs
-
-When Adaptive Server Anywhere databases are initialized, two groups and two
-user IDs are created. The two groups created are SYS and PUBLIC. The two user
-IDs created are DBA and dbo.
-
-SYS is a user as well as a group, but no one can connect to the database
-using the user ID SYS. SYS owns the system tables and the system views, and
-only SYS can update the system tables.
-
-PUBLIC is a member of the SYS group, and has only SELECT permissions on most
-system tables and system views. Since new user IDs are, by default, members
-of PUBLIC, you should revoke PUBLIC's membership in SYS if you want new users
-to have no permissions by default.
-
-The DBA user can directly modify any part of an Adaptive Server Anywhere
-database except the system tables. This is why it's important to change the
-default DBA password from "SQL." You should be cautious when giving DBA
-authority to a user (see the DBA Authority section below). If a user needs
-DBA authority, s/he should be given DBA authority, rather than the DBA's
-password.
------------------------------------------------------------------------------
-
-6.2.1.2. Creating new user IDs
-
-The SQL statement to add a new user ID is GRANT CONNECT.
-
-Syntax:
-GRANT CONNECT TO userid1
- IDENTIFIED BY password1
-
-To add a user ID with the name Mortimer, execute the following SQL statement:
-grant connect to mortimer identified by
-monkey
------------------------------------------------------------------------------
-
-6.2.2. Permissions
-
-This section explains permissions on tables that can be granted to users.
-Permissions are granted on a user-by-user basis.
-
-There are a few different table permissions that can be granted to a user,
-and they are each granted separately.
-
- * SELECT allows the user to read data, and can be restricted to particular
- columns.
-
- * INSERT allows the user to add data.
-
- * UPDATE allows the user to change data, and can be restricted to
- particular columns.
-
- * DELETE allows the user to remove data.
-
- * ALTER allows the user to modify the structure of a table.
-
- * REFERENCES allows the user to add indexes, primary keys, and foreign
- keys.
-
- * ALL includes all the above permissions.
-
-
-With the exceptions of ALTER and REFERENCES, which apply to tables
-exclusively, the table permissions apply to both tables and views. The SQL
-syntax for granting permissions is as follows:
-GRANT [ SELECT (column-name, ...)
- | INSERT
- | UPDATE (column-name, ...)
- | DELETE
- | ALTER
- | REFERENCES
- | ALL ]
-ON table-name
-TO userid
-
-The user userid is given the specified permission(s) on the table identified
-by table-name. If the permissions granted include SELECT and/or UPDATE, they
-are granted only on the columns specified in column-name.
-
-Let's say a list of available banana types is stored in the type and quantity
-columns of a table named banana_supply. To allow Mortimer to see a list of
-available banana types along with their quantities, use the following SQL
-statement:
-
-grant select on banana_supply (type, quantity) to mortimer
-
-When you grant a permission to a user, you have the option of granting him
-the ability to grant that same permission to others. To grant a user the
-permission to do so, add WITH GRANT OPTION to the end of your users GRANT
-statement when you're granting them their permissions.
-
-To allow Mortimer to see a list of banana types available along with the
-quantities of each, as well as allowing him to grant others the same SELECT
-permission, use this SQL statement:
-grant select on banana_supply (type, quantity)
-to mortimer
- with grant option
------------------------------------------------------------------------------
-
-6.2.3. Authorities
-
-An authority is a different level of permission. There are two types of
-authority.
------------------------------------------------------------------------------
-
-6.2.3.1. RESOURCE authority
-
-A user with the RESOURCE authority can create and drop database objects such
-as tables, views, stored procedures, and functions. The RESOURCE authority
-also allows the user to create and remove user IDs and passwords. To give
-userid the RESOURCE authority, execute the following SQL statement:
-
-GRANT RESOURCE TO userid
------------------------------------------------------------------------------
-
-6.2.3.2. DBA authority
-
-A user with the DBA authority can perform any database operation, and
-automatically has all permissions on all tables, except the system tables.
-The DBA can create and remove user IDs and passwords, grant RESOURCE and DBA
-authority, and unload and reload the database.
-
-GRANT DBA TO userid
------------------------------------------------------------------------------
-
-6.2.4. Removing Users and Revoking Permissions
-
-The SQL statement to delete a user ID is REVOKE CONNECT.
-
-Syntax:
-
-REVOKE CONNECT FROM userid [, userid ]
-
-As suggested by the portions in square parentheses, it's possible to remove
-multiple user IDs in a single statement. For example, to remove the user IDs
-for Mortimer and Chestington, execute this statement:
-
-revoke connect from mortimer, chestington
-
-To revoke permissions or authorities given to a particular user, you take the
-original granting statement, replace the GRANT with REVOKE, and replace the
-TO with FROM. To take away Mortimer's permission to view the banana_supply
-table, for example, use this REVOKE statement:
-
-revoke select on banana_supply (type, quantity) from mortimer
------------------------------------------------------------------------------
-
-6.2.5. Changing Passwords
-
-To change the password associated with a particular user ID, use a GRANT
-CONNECT statement again:
-
-GRANT CONNECT TO userid IDENTIFIED BY newpassword
-
-For example, to change the DBA's password from "SQL" to "d0n13xw9," use this
-statement:
-
-grant connect to DBA identified by d0n13xw9
------------------------------------------------------------------------------
-
-6.3. Making the database more secure
-
-Some of the Adaptive Server Anywhere features you may wish to use in building
-a secure environment for your data include the following:
-
- * User identification and authentication control access to databases.
-
- * Permissions and authorities, which have already been explained in
- previous sections, control the actions a user can carry out while
- connected to a database.
-
- * Views and stored procedures allow you to carefully tune the data a user
- can access and the operations a user can execute.
-
- * Connection encryption can prevent unauthorized persons from snooping.
-
-
-Some of these features have already been mentioned in this HOWTO, and some of
-them will be elaborated upon in the following sections. While the concepts of
-triggers, procedures, and views will be introduced so you can decide if and
-how you'll use them, their implementation won't be discussed. You can find
-indepth information on them, as well as details on their implementation, in
-the sections of the Adaptive Server Anywhere User's Guide listed below:
-
-
-Table 8.
-+----------------------------------------+---------------------------------------------------------------+
-|Chapter |Section |
-+----------------------------------------+---------------------------------------------------------------+
-|Using Procedures, Triggers, and Batches |Benefits of procedures and triggers |
-+----------------------------------------+---------------------------------------------------------------+
-|Managing User IDs and Permissions |Using views and procedures for extra security |
-+----------------------------------------+---------------------------------------------------------------+
------------------------------------------------------------------------------
-
-6.3.1. Increasing password security
-
-By default, passwords can be any length. For greater security, you can
-enforce a minimum length on all new passwords, to make them more difficult to
-guess. You do this by setting the MIN_PASSWORD_LENGTH database option to a
-greater value. The following statement enforces a minimum password length of
-8 characters:
-
-set option public.min_password_length = 8
-
-Check the "Changing Passwords" section of this document to learn how to
-change a user's password, and don't forget to change the DBA's password!
------------------------------------------------------------------------------
-
-6.3.2. Views, procedures, and triggers
-
-Views are useful when it is appropriate to give a user access to just one
-portion of a table. The portion can be defined in terms of rows or in terms
-of columns. For example, you may wish to prevent a group of users from seeing
-the quantity column of the banana_supply table, or you may wish to limit a
-user to see information on a particular type of banana.
-
-While views restrict access based on the data, procedures and triggers
-restrict access based on the actions a user can take. Procedures and triggers
-store SQL statements in a database for use by all applications. They execute
-under the table permissions of the associated table's owner, regardless of
-the permissions of the user who either executes the procedure or fires the
-trigger.
-
-Procedures are invoked by a CALL statement, and can take values as well as
-return them. Unlike procedures, however, triggers are can neither take values
-nor return them, and are invoked by insertions, updates, or deletions in the
-table it is associated with. Permissions are not associated with triggers.
-They execute when the action defined to fire them is performed, regardless of
-the user.
-
-For strict security, you can prevent all access to the tables, and grant
-permission to users to execute certain stored procedures that carry out
-specific tasks. This approach strictly defines the manner in which the
-database can be modified.
------------------------------------------------------------------------------
-
-6.3.3. Encrypting client/server communications
-
-Encrypting client/server communications prevents third parties from reading
-messages being sent between the client and the server. It can be enabled from
-either the server side or the client side. To enable encryption from the
-server, use the -e option at server startup. For example, use the following
-command to start up the database server to accept encrypted connections to
-mydb.db over TCP/IP:
-
-dbsrv7 -e -x tcpip mydb.db
-
-To enable encryption from a particular client, use the ENC keyword in the
-connection string. For example, to encrypt a connection over TCP/IP to
-mydb.db, your connection string would appear as follows:
-
-"uid=mortimer;pwd=monkey;links=tcpip;eng=MyServer;dbf=mydb.db;enc=true"
-
-For more information about client/server communications encryption, look for
-the -e command-line option under "The database server" in the Adaptive Server
-Anywhere Reference Manual, and for "Encryption connection parameter" under
-"Connection parameters" .
------------------------------------------------------------------------------
-
-7. Where to get more information
-
-On-line help is available on your cdrom. If your computer is set up to mount
-the CD-ROM to /mnt/cdrom/ the help is located in /mnt/cdrom/help/
-contents.htm. Open it with Netscape Navigator, or any other web browser that
-supports tables. Style sheets support is recommended, but not necessary.
-
-A FAQ is available for the UNIX version of Adaptive Server Anywhere at [http:
-//www.sybase.com/detail/1,3693,1011965,00.html] http://www.sybase.com/detail/
-1,3693,1011965,00.html
-
-Check if there have been any bug fixes or updates posted at [http://
-downloads.sybase.com/swx/sdmain.stm] http://downloads.sybase.com/swx/
-sdmain.stm.
-
-Newsgroups can be read from the web or with a news reader. The newsgroups
-sybase.public.sqlanywhere.general and sybase.public.sqlanywhere.linux are
-most likely to be relevant. To view newsgroups on the web, visit [http://
-www.sybase.com/support/newsgroups] http://www.sybase.com/support/newsgroups.
-Be sure to search old threads for similar problems. It may already have been
-resolved.
------------------------------------------------------------------------------
-
-8. Legalities and Acknowledgements
-
-8.1. Copyright and Licenses
-
-Copyright (c) 2001 Sybase Inc.
-
-This manual may be reproduced in whole or in part, without fee, subject to
-the following restrictions:
-
- * The copyright notice above and this permission notice must be preserved
- complete on all complete or partial copies.
-
- * Any translation or derived work must be approved by the author in writing
- before distribution.
-
- * If you distribute this work in part, instructions for obtaining the
- complete version of this manual must be included, and a means for
- obtaining a complete version provided.
-
- * Small portions may be reproduced as illustrations for reviews or quotes
- in other works without this permission notice if proper citation is
- given. Exceptions to these rules may be granted for academic purposes:
- Use the contact information in the next section to ask. These
- restrictions are here to protect us as authors, not to restrict you as
- learners and educators. Any source code (aside from the DocBook this
- document was written in) in this document is placed under the GNU General
- Public License, available via anonymous FTP from the GNU archive.
-
-
-The preceding notice was borrowed and tweaked from the LDP Author Guide's
-copyright notice.
------------------------------------------------------------------------------
-
-8.2. Names and Contacts
-
-This document was initiated by Michael Moller and (mostly) written by Aylwin
-Lo with assistance from Michael Heal and Tom Slee. We work at Sybase.
-
-Since the author is a co-op student, the best way to contact someone
-regarding this document is by posting to the sybase.public.sqlanywhere.linux
-newsgroup, available on the forums.sybase.com news server.
------------------------------------------------------------------------------
-
-8.3. Acknowledgement
-
-Thanks to the folks at [http://www.commandprompt.com/] http://
-www.commandprompt.com/ for getting the text of this HOWTO into workable SGML
-for us.
+* Sybase Adaptive Server Anywhere for Linux HOWTO
diff --git a/LDP/guide/docbook/Linux-Networking/Email-Hosting.xml b/LDP/guide/docbook/Linux-Networking/Email-Hosting.xml
index 7157212b..936b9b11 100644
--- a/LDP/guide/docbook/Linux-Networking/Email-Hosting.xml
+++ b/LDP/guide/docbook/Linux-Networking/Email-Hosting.xml
@@ -3,3563 +3,15 @@
Email
-Alongside the Web, mail is the top reason for the popularity of the Internet. Email is an inexpensive and fast
-method of time-shifted messaging which, much like the Web, is actually based around sending and receiving
-plain text files. The protocol used is called the Simple Mail Transfer Protocol (SMTP). The server programs
-that implement SMTP to move mail from one server to another are called Mail Transfer Agents (MTAs).
+Alongside the Web, mail is the top reason for the popularity of the Internet. Email is an inexpensive and fast method of time-shifted messaging which, much like the Web, is actually based around sending and receiving plain text files. The protocol used is called the Simple Mail Transfer Protocol (SMTP). The server programs that implement SMTP to move mail from one server to another are called Mail Transfer Agents (MTAs).
+
-In times gone by, users would Telnet into the SMTP server itself and use a command line program like elm
-or pine to check ther mail. These days, users run email clients like Netscape, Evolution, Kmail or
-Outlook on their desktop to check their email off a local SMTP server. Additional protocols like POP3 and
-IMAP4 are used between the SMTP server and desktop mail client to allow clients to manipulate files on,
-and download from, their local mail server. The programs that implement POP3 and IMAP4 are called Mail
-Delivery Agents (MDAs). They are generally separate from MTAs.
+
+In times gone by, users would Telnet into the SMTP server itself and use a command line program like elm or pine to check ther mail. These days, users run email clients like Netscape, Evolution, Kmail or Outlook on their desktop to check their email off a local SMTP server. Additional protocols like POP3 and IMAP4 are used between the SMTP server and desktop mail client to allow clients to manipulate files on, and download from, their local mail server. The programs that implement POP3 and IMAP4 are called Mail Delivery Agents (MDAs). They are generally separate from MTAs.
- 6.1. Mail
-
- 6.1.1. Mail servers
-
- Sendmail is the de facto standard mail server program (called an MTA,
- or Mail Transport Agent) for Unix platforms. It is robust, scalable,
- and properly configured and with the necessary hardware, can handle
- loads of thousands of users without blinking. Alternative mail
- servers, such as smail and qmail, are also available.
-
-
- · Sendmail web site
-
- · Smail faq
-
- · Qmail web site
-
- Mail HOWTOs:
-
- · http://metalab.unc.edu/mdw/HOWTO/Mail-User-HOWTO.html
-
- · http://metalab.unc.edu/mdw/HOWTO/mini/Qmail+MH.html
-
- · http://metalab.unc.edu/mdw/HOWTO/mini/Sendmail+UUCP.html
-
- · http://metalab.unc.edu/mdw/HOWTO/mini/Mail-Queue.html
-
-
- 6.1.2. Remote access to mail
-
- In an organisation or ISP, users will likely access their mail
- remotely from their desktops. Several alternatives exist in Linux,
- including POP (Post Office Protocol) and IMAP (Internet Message Access
- Protocol) servers. The POP protocol is usually used to transfer
- messages from the server to the client. IMAP permits also manipulation
- of the messages in the server, remote creation and deletion of folders
- in the server, concurrent access to shared mail folders, etc.
-
-
- · Brief comparison IMAP and POP
-
-
- Mail related HOWTOs:
-
- · http://metalab.unc.edu/mdw/HOWTO/Mail-User-HOWTO.html
-
- · http://metalab.unc.edu/mdw/HOWTO/Cyrus-IMAP.html
-
-
- 6.1.3. Mail User Agents
-
- There are a number of MUA (Mail User Agents) in Linux, both graphical
- and text mode. The most widely used ones include: pine, elm, mutt and
- Netscape.
-
-
- · List of mail related software
-
-
- · http://metalab.unc.edu/mdw/HOWTO/mini/TkRat.html
-
-
- 6.1.4. Mailing list software
-
- There are many MLM (Mail List Management) programs available for Unix
- in general and for Linux in particular.
-
-
- · A good comparison of existing MLMs may be found
- at:ftp://ftp.uu.net/usenet/news.answers/mail/list-admin/
-
- · Listserv
-
- · Majordomo home page
-
-
- 6.1.5. Fetchmail
-
- One userful mail-related utility is fetchmail. Fetchmail is a free,
- full-featured, robust, well-documented remote-mail retrieval and
- forwarding utility intended to be used over on-demand TCP/IP links
- (such as SLIP or PPP connections). It supports every remote-mail
- protocol now in use on the Internet. It can even support IPv6 and
- IPSEC.
-
- Fetchmail retrieves mail from remote mail servers and forwards it via
- SMTP, so it can then be be read by normal mail user agents such as
- mutt, elm or BSD Mail. It allows all the system MTA's filtering,
- forwarding, and aliasing facilities to work just as they would on
- normal mail.
-
- Fetchmail can be used as a POP/IMAP-to-SMTP gateway for an entire DNS
- domain, collecting mail from a single drop box on an ISP and SMTP-
- forwarding it based on header addresses.
-
- A small company may centralise its mail in a single mailbox, configure
- fetchmail to collect all outgoing mail, send it via a single mailbox
- at their ISP and retrieve all incoming mail from the same mailbox.
-
-
- · Fetchmail home page
-
-
-
- This section will describe the setup, care and feeding of Electronic Mail
- (e-mail) under Linux. It is primarily intended for administrators,
- rather than users. (See the Mail-User's-HOWTO for information on user
- issues and user agents.) You need to read this if you plan to commu
- nicate locally or to remote sites via electronic mail. You probably
- do *not* need to read this document if don't exchange electronic mail
- with other users on your system or with other sites.
-
- 1.2. Goals
-
- The intent of this document is to answer some of the questions and
- comments that appear to meet the definition of "frequently asked
- questions" about e-mail software under Linux in general and the
- version in the Linux Debian and RedHat distributions in particular.
-
- 1.3. New versions
-
- New versions of this document will be periodically posted to
- comp.os.linux.announce, comp.answers and mail.answers. They will also
- be added to the various anonymous ftp sites who archive such
- information including sunsite.unc.edu:/pub/Linux/docs/HOWTO.
-
- In addition, you should be generally able to find this document on the
- Linux WorldWideWeb home page at http://sunsite.unc.edu/mdw/linux.html.
-
- 1.4. Feedback
-
- I am interested in any feedback, positive or negative, regarding the
- content of this document via e-mail. Definitely contact me if you
- find errors or obvious omissions.
-
- I read, but do not necessarily respond to, all e-mail I receive.
- Requests for enhancements will be considered and acted upon based on
- that day's combination of available time, merit of the request and
- daily blood pressure :-)
-
- Flames will quietly go to /dev/null so don't bother.
-
- Feedback concerning the actual format of the document should go to the
- HOWTO coordinator : Tim Bynum (howto at wallybox.cei.net).
-
- 2. Other sources of information
-
- 2.1. There is a Mail User's HOWTO, which focuses on user issues. It
- is currently maintained by Eric S. Raymond; you should be able to view
- it on the World Wide Web at urlnam . Mail User's HOWTO
-
- 2.2. USENET
-
- There is nothing special about configuring and running mail software
- under Linux (any more). Accordingly, you almost certainly do NOT want
- to be posting generic mail-related questions to the comp.os.linux.*
- newsgroups.
-
- Don't post in comp.os.linux hierarchy unless it's really linux
- specific, for example : "Which options was Debian 1.2 sendmail
- compiled with ?" or "RedHat 5.0 smail crashes when I run it".
-
- Let me repeat that.
-
- There is virtually no reason to post anything mail-related in the
- comp.os.linux hierarchy any more. There are existing newsgroups in
- the comp.mail.* hierarchy to handle *ALL* your questions.
-
- IF YOU POST TO COMP.OS.LINUX.* FOR NON-LINUX-SPECIFIC QUESTIONS, YOU
- ARE LOOKING IN THE WRONG PLACE FOR HELP. THE MAIL EXPERTS HANG OUT IN
- THE PLACES INDICATED ABOVE AND GENERALLY DO NOT RUN LINUX.
-
- POSTING TO THE LINUX HIERARCHY FOR NON-LINUX-SPECIFIC QUESTIONS WASTES
- YOUR TIME AND EVERYONE ELSE'S AND IT FREQUENTLY DELAYS YOUR GETTING
- THE ANSWER TO YOUR QUESTION.
- GOOD PLACES are :
-
- comp.mail.elm the ELM mail system.
- comp.mail.mh The Rand Message Handling system.
- comp.mail.mime Multipurpose Internet Mail Extensions.
- comp.mail.misc General discussions about computer mail.
- comp.mail.multi-media Multimedia Mail.
- comp.mail.mush The Mail User's Shell (MUSH).
- comp.mail.sendmail the BSD sendmail agent.
- comp.mail.smail the smail mail agent.
- comp.mail.uucp Mail in the uucp environment.
-
- 2.3. Mailing Lists
-
- There are many sendmail, smail and qmail mailing lists.
-
- You can find addresses in /usr/doc/the_one_you_have_chosen.
-
- 2.4. Other documents from LDP
-
-
- There is plenty of excellent material provided in the other Linux
- HOWTO documents and from the Linux DOC project.
-
- In particular, you might want to take a look at the following:
-
- · on your own computer in /usr/doc/ :-)
- · the Linux Networking Administrators' Guide
- · the Mail Users HOWTO
- · the Serial Communications HOWTO
- · the Ethernet HOWTO
- · the UUCP HOWTO if you're fed via UUCP
-
- 2.5. Books
-
- The following is a non-inclusive set of books that will help:
-
- · "Managing UUCP and USENET" from O'Reilly and Associates is in my
- opinion the best book out there for figuring out the programs and
- protocols involved in being a USENET site.
-
- · "Unix Communications" from The Waite Group contains a nice
- description of all the pieces (and more) and how they fit together.
-
- · "Sendmail" from O'Reilly and Associates looks to be the definitive
- reference on sendmail-v8 and sendmail+IDA. It's a "must have" for
- anybody hoping to make sense out of sendmail without bleeding in
- the process.
-
- · "The Internet Complete Reference" from Osborne is a fine reference
- book that explains the various services available on Internet and
- is a great source for information on news, mail and various other
- Internet resources.
-
- · "The Linux Networking Administrators' Guide" from Olaf Kirch of the
- Linux Documentation Project is available on the net and is also
- published by (at least) O'Reilly and SSC.
-
- It makes a fine one-stop shop to learn about everything you ever
- imagined you'd need to know about Unix networking.
-
- 3. How Electronic Mail Works
-
- Now we'll explain the flow of information that typically takes place
- when two people to communicate by email. Let us suppose that Alice,
- on her machine wonderland.com, wants to send mail to Bob, on his
- machine dobbs.com. Both machines are connected to the Internet.
-
- It helps to know that an Internet mail message consists of two parts;
- mail headers and a mail body, separated by a blank line. The mail
- headers contain the source and destination of the mail, a user-
- supplied subject line, the date it was sent, and various other kinds
- of useful information. The body is the actual content of the message.
- Here's an example:
-
-
- From: "Alice"
- Message-Id: <199711131704.MAA18447@wonderland.com>
- Subject: Have you seen my white rabbit?
- To: bob@dobbs.org (Bob)
- Date: Thu, 13 Nov 1997 12:04:05 -0500 (EST)
- Content-Type: text
-
- I'm most concerned. I fear he may have fallen down a hole.
- --
- >>alice>>
-
-
-
- The arrangement and meaning of Internet mail headers are defined by an
- Internet standard called RFC822 .
-
-
- 3.1. Mail between full-time Internet machines
-
- Here's a diagram of the whole process -- I'll explain all the stages
- and terminology below.
-
-
-
- ______________________________________________________________________
- +---------+ +-------+
- +-------+ types | sending | calls |sending|
- | Alice |--------->| MUA |--------->| MTA |::::>::::
- +-------+ | | | | :: on the
- +---------+ +-------+ :: sending
- :: machine
- .......................................................................
- SMTP ::
- ::::::::::::::::::::::::::::<::::::::::::::::::::::::::::
- ::
- :: +---------+ +-----+ +-------+
- :: |receiving| calls | | delivers to | Bob's |
- ::::>| MTA |--------->| LDA |===============>|mailbox| on the
- | | | | | | receiving
- +---------+ +-----+ +-------+ machine
- | |
- | |
- +----------------<-------------+ |
- | |
- +---------+ +-------+ |
- | Bob's | | Bob's |<----------+
- | notifier| | MUA |
- +---------+ +-------+
- | |
- | +-----+ |
- +----->| Bob |<----+
- +-----+
- ______________________________________________________________________
-
-
-
- To send mail, Alice will invoke a program called a mail user agent (or
- MUA for short). The MUA is what users think of as `the mailer'; it
- helps her compose the message, usually by calling out to a text editor
- of her choice. When she hits the MUA `send' button, her part of the
- process is done. Later in this HOWTO we will survey popular MUAs.
-
- The MUA she uses immediately hands her message to a program called a
- mail transport agent (or MTA). Usually this program will be sendmail,
- though some alternative MTAs are gaining popularity and may appear in
- future Linux distributions. Later in this HOWTO we will also survey
- MTAs.
-
- The MTA's job is to pass the mail to an MTA on Bob's machine. It
- determines Bob's machine by analyzing the To header and seeing the
- dobbs.com on the right-hand side of Bob's address. It uses that
- address to open an Internet connection to Bob's machine. The
- mechanics of making that connection are a whole other topic; for this
- explanation, it's enough to know that that connection is a way for
- Alice's MTA to send text commands to Bob's machine and receive replies
- to those commands.
-
- The MTA's commands don't go to a shell. Instead they go to a service
- port on Alice's machine. A service port is a sort of rendezvous, a
- known place where Internet service programs listen for incoming
- requests. Service ports are numbered, and Alice's MTA knows that it
- needs to talk to port 25 on Bob's machine to pass mail.
-
- On port 25, Bob's machine has its own MTA listening for commands
- (probably another copy of sendmail). Alice's MTA will go through a
- dialogue with Bob's using Simple Mail Transfer Protocol (or SMTP).
- Here is what an SMTP dialogue looks like. Lines sent by Alice's
- machine are shown with S:, responses from Bob's machine are shown with
- R:.
-
- S: MAIL FROM:
- R: 250 OK
- S: RCPT TO:
- R: 250 OK
- S: DATA
- R: 354 Start mail input; end with .
- S: From: "Alice"
- S: Message-Id: <199711131704.MAA18447@wonderland.com>
- S: Subject: Have you seen my white rabbit?
- S: To: bob@dobbs.org (Bob)
- S: Date: Thu, 13 Nov 1997 12:04:05 -0500 (EST)
- S: Content-Type: text
- S:
- S: I'm most concerned. I fear he may have fallen down a hole.
- S: --
- S: >>alice>>
- S: .
- R: 250 OK
-
-
-
- Usually an SMTP command is a single text line and so is its response.
- The DATA command is an exception; after seeing that, the SMTP listener
- accepts message lines until it sees a period on a line by itself.
- (SMTP is defined by the Internet standard RFC821
- .)
-
- Now Bob's MTA has Alice's message. It will add a header to the
- message that looks something like this:
-
-
- Received: (from alice@wonderland.com)
- by mail.dobbs.com (8.8.5/8.8.5) id MAA18447
- for bob@dobbs.com; Thu, 13 Nov 1997 12:04:05 -0500
-
-
-
- This is for tracking purposes in case of mail errors (sometimes a
- message has to be relayed through more than one machine and will have
- several of these). Bob's MTA will pass the modified message to a
- local delivery agent or LDA. On Linux systems the LDA is usually a
- program called procmail, though others exist.
-
- The LDA's job is to append the message to Bob's mailbox. It's
- separate from the MTA so that both programs can be simpler, and so the
- MTA can concentrate on doing Internet things without worrying about
- local details like where the user mailboxes live.
-
- Bob's mailbox will normally be a file called /usr/spool/mail/bob or
- /var/mail/bob. When he reads mail, he runs his own MUA (mail user
- agent) to look at and edit that file.
-
-
- 3.2. Notifiers
-
- There's yet another kind of program that is important in the mail
- chain, though it does not itself read or transmit mail. It's a mail
- notifier, a program that watches your email in-box for activity and
- signals you when new mail is present.
-
- The original notifier was a pair of Unix programs called biff(1) and
- comsat(8). The biff program is a front end that enables you to turn on
- the comsat service. When this service is on, the header of new mail
- will be dumped to your terminal as it arrived. This facility was
- designed for people using line-oriented programs on CRTs; it's not
- really a good idea in today's environment.
- Most Unix shells have built-in mailcheck facilities that allow them to
- function as notifiers in a rather less intrusive way (by emitting a
- message just before the prompt when new mail is detected). Typically
- you can enable this by setting environment variables documented on the
- shell's manual page. For shells in the sh/ksh/bash family, see the
- MAIL and MAILPATH variables
-
- Systems supporting X come with one of several little desktop gadgets
- that check for new mail periodically and give you both visible and
- audible indication of new mail. The oldest and most widely used of
- these is called xbiff; if your Linux has a preconfigured X desktop
- setup, xbiff is probably on it. See the xbiff(1) manual page for
- details.
-
-
- 3.3. Mail to part-time Internet machines
-
- If you were reading carefully, you may have noticed that the
- information flow we described above depends on Alice's machine being
- able to talk to Bob's machine immediately. What happens if Bob's
- machine is down, or is up but not connected to the Internet?
-
- If Alice's MTA can't reach Bob's immediately, it will stash Alice's
- message in a mail queue on wonderland.com. It will then retry sending
- the mail at intervals until an expiration time is reached, at which
- point a bounce message notifying Alice of the failure will be sent
- back to her. In the default configuration of the most popular MTA
- (sendmail), the retry interval is 15 minutes and the expiration time
- is 4 days.
-
-
- 3.4. Remote mail and remote-mail protocols
-
- Many Linux users nowadays are connected to the Internet via ISPs
- (Internet Service Providers) and don't have their own Internet
- domains. Instead they have accounts on an ISP machine. Their mail
- gets delivered to a mailbox on that ISP machine. But typically these
- users want to read and reply to their mail using their own machines,
- which connect to the ISP intermittently using SLIP or PPP. Linux
- supports remote mail protocols to support this.
-
- Note how this is different from the scenario we discussed in the last
- section. Mail sitting in a queue awaiting retransmission is not the
- same as mail dispatched to a server mailbox; mail in a queue is not
- considered to have been delivered and is subject to expiration, but
- mail delivered to an ISP server mailbox is considered `delivered' and
- can sit there indefinitely.
-
- A remote-mail protocol allows mail on a server to be pulled across a
- network link by a client program (this is the opposite of normal
- delivery in which an MTA pushes mail to a receiving MTA). There are
- two remote-mail protocols in common use; POP3 (defined by the Internet
- standard RFC1939 ) and IMAP
- (defined by the Internet standard RFC2060 ). Effectively all ISPs support POP3; a growing
- number support IMAP (which is more powerful).
-
- Here is what an example POP3 session looks like:
-
-
-
- S:
- R: +OK POP3 server ready <1896.697170952@mailgate.dobbs.org>
- S: USER bob
- R: +OK bob
- S: PASS redqueen
- R: +OK bob's maildrop has 2 messages (320 octets)
- S: STAT
- R: +OK 2 320
- S: LIST
- R: +OK 2 messages (320 octets)
- R: 1 120
- R: 2 200
- R: .
- S: RETR 1
- R: +OK 120 octets
- R:
- R: .
- S: DELE 1
- R: +OK message 1 deleted
- S: RETR 2
- R: +OK 200 octets
- R:
- R: .
- S: DELE 2
- R: +OK message 2 deleted
- S: QUIT
- R: +OK dewey POP3 server signing off (maildrop empty)
- S:
-
-
-
- An IMAP session uses different commands and responses, but is
- logically very similar.
-
-
- To take advantage of POP3 or IMAP, you need a remote mail client
- program to pull your mail. Some mail user agents have client
- capabilities built in (which one supports which is noted below), and
- the Netscape browser's mail facility supports both POP and IMAP
- natively.
-
- The main drawback of POP client facilities built into MUAs is that you
- have to explicitly tell your mailer to poll the server; you don't get
- notified by xbiff(1) or equivalent, as you would for mail that is
- either local or delivered by a conventional SMTP `push' connection.
- Also, of course, not all MUAs can do POP/IMAP, so you may find
- yourself compromising on other features.
-
- Your Linux probably comes with a program called fetchmail
- that is designed specifically
- to talk to remote-mail servers, fetch mail, and feed it into your
- normal mail delivery path by speaking SMTP to your listener.
-
- Unless you need to keep your mail on the server (for example, because
- you move around between client machines a lot) fetchmail is probably a
- better solution than whatever POP/IMAP features your user agent has.
- Fetchmail can be told to run in background and poll your server
- periodically, so your xbiff(1) or other mail-notifier program will
- work as it would for SMTP mail. Also, fetchmail is rather more
- tolerant of various idiosyncracies and nonstandard server quirks than
- the clients in MUAs, and has better error recovery.
-
- Here's a diagram showing how both cases (with and without fetchmail)
- work:
-
-
- ______________________________________________________________________
- +---------+ +-------+
- +-------+ types | sending | calls |sending|
- | Alice |--------->| MUA |--------->| MTA |::::>::::
- +-------+ | | | | ::
- +---------+ +-------+ :: on the
- :: sending
- SMTP :: machine
- ::::::::::::::::::::::::::::<::::::::::::::::::::::::::::
- ::
- .::.......................................................................
- ::
- :: +---------+ +-----+ +-------+
- :: |receiving| calls | | delivers | Bob's |
- ::::>| MTA |--------->| LDA |============>|server |::::>::::
- | | | | to |mailbox| :: on the
- +---------+ +-----+ +-------+ :: mail
- :: server
- POP or IMAP ::
- ::::::::::::::::::::::::::::<:::::::::::::::::::::::::::::::::::
- ::
- .::........................................................................
- ::
- :: +-----------+
- :: | |
- :::::::>::::::::::::| fetchmail |:::::::: on the
- :: | | :: receiving
- :: +-----------+ :: machine,
- :: :: with fetchmail
- :: ::::::::::::::::<:::::::::::::::::::
- :: ::
- :: :: +---------+ +-----+ +-------+
- :: :: |receiving| calls | | delivers to | Bob's |
- :: ::::>| MTA |--------->| LDA |===============>|mailbox|
- :: | | | | | |
- :: +---------+ +-----+ +-------+
- :: | |
- :: | |
- :: +----------------<-------------+ |
- :: | |
- :: +---------+ +-------+ |
- :: | Bob's | | Bob's |<----------+
- :: | notifier| | MUA |
- :: +---------+ +-------+
- :: | |
- .::........................................................................
- :: . | |
- :: without . | |
- :: fetchmail . | |
- :: . | +-----+ |
- :: +----------+ . +----->| |<----+
- :: | Bob's | . | Bob |
- :::::| POP/IMAP |----.--------->| |
- | MUA | . +-----+
- +----------+ .
- ______________________________________________________________________
-
-
-
- 3.5. Mailbox formats
-
- When incoming mail gets appended to a mailbox, it's up to the MTA to
- provide some kind of delimiters that tell where one message stops and
- the next begins.
- Under Unix, the convention almost all mailers use is that each line
- beginning with ``From '' (the space is significant) begins a new
- message. If ``From '' occurs at the beginning of a line in text, a
- Unix MTA will generally prefix it with a greater-than sign, so it
- looks like ``>From ''. RFC822 headers follow this From line (which
- usually continues with the sender name and receipt date).
-
- This convention originated with Unix Version 7, so this kind of
- mailbox is referred to as a ``V7 mailbox''; it is also sometimes
- called ``mbox format''. Unless otherwise noted, all programs
- mentioned in this HOWTO expect this format. It is not, however, quite
- universal, and tools expecting and generating different formats can
- confuse each other badly.
-
- The four other formats to know about (and beware of!) are BABYL, MMDF,
- MH, and qmail maildir. Of these, MMDF is the simplest; it uses a
- delimiter line consisting four control-As (ASCII 001) characters
- followed by CR-LF. MMDF was an early and rather crude Internet mail
- transport; a descendant is still in use on SCO systems.
-
- BABYL is another survival, from an early mail system at MIT. It is
- still used by Emacs's mail-reader mode.
-
- MH and qmail maildir are `mailbox' formats which actually burst each
- mailbox into a directory of files, one per message. Running grep on
- such a `mailbox' will get you nowhere, since all grep will see are the
- directory bits.
-
- Microsoft Outlook Express .mbx mailboxes can be converted to RFC822
- format with mbx2mbox app.
-
-
- 4. Requirements
-
-
-
- 4.1. Hardware
-
-
- There are no specific hardware requirements for mail under Linux.
-
- You'll need some sort of 'transport' software to connect to remote
- systems, which means either TCP/IP or uucp.
-
- This could mean that you need a modem or ethernet card, depending on
- your setup. In most cases, you'll want the fastest modem you can
- afford, i.e. V90 57 600 bps currently. In general, you want to have a
- 16550 UART on your serial board or built into your modem to handle
- speeds of above 9600 baud.
-
- If you don't know what that last sentence means, please consult the
- comp.dcom.modems group or the various fine modem and serial
- communications FAQs and periodic postings on USENET.
-
-
- 5. Choosing a Mail Transport Agent
-
- Mail transport agents are the software that transfers mail from your
- local system to remote systems. It is very seldom necessary to mess
- with or replace your MTA on a modern Linux, and you're better off not
- fixing what isn't broken. Nevertheless, here's a survey to get you
- started on understanding what the tradeoffs are if you decide you need
- more security or performance than your system's default can offer.
-
- (There are other Unix MTAs besides these, but you are quite unlikely
- to encounter them on a Linux box.)
- Each has its own unique features, but the best compromise is qmail. It
- features high security (even if vmail is more secure), high speed
- (even if smail is faster for local uses) and ease of configuration.
- Of course, feel free to choose any mail software. The information
- provided here is intended to help you choose well.
-
- Sendmail can be nice for many sites with complicated options, but I
- think its configuration is too hard for beginners while it is not very
- secure or very fast, so there is only a really outdated sendmail
- section in this HOWTO.
-
- If you know what you're doing, choose sendmail (and you shouldn't be
- reading this HOWTO!); otherwise I generally recommend qmail.
-
- Detailed descriptions of these programs follow.
-
-
- 5.1. sendmail
-
- BSD sendmail is the grandaddy of Internet MTAs. It has outlasted a
- few would-be successors. Most Linux distributions now use it and have
- it preinstalled.
-
-
- Sendmail has a long-standing reputation for being an administrator's
- nightmare -- hard to understand, tricky to configure, rife with
- security holes. As Internet technology and standards have stabilized,
- however, many of the sendmail options and configurable rules that gave
- rise to this reputation have ceased to require per-site tweaking (the
- effective demise of non-TCP/IP network layers like UUCP has helped a
- lot). Also, recent sendmail versions have an improved configuration
- system that insulates you from the legendary hideousness of the
- sendmail.cf configuration file. Most importantly, sendmail now
- normally comes preconfigured, and you should never need to touch it
- unless you have unusual requirements (such as needing to route mail
- over a non-TCP/IP network).
-
-
- There is a sendmail home page at . It
- includes references to extensive documentation of sendmail, should you
- actually need to wrestle with custom-configuring it.
-
-
- Other MTAs, if called as `sendmail', may mimic the semantics of
- sendmail's command-line options. This is convenient for mail user
- agents, which often assume they are talking to sendmail.
-
-
-
- 5.2. smail v3.2
-
- Smail was the first serious attempt to replace sendmail. It has a
- simpler and much more comprehensible configuration system than
- sendmail's, and it's fairly secure. Some Linux distributions
- preinstall it rather than sendmail.
-
-
- At one time smail's excellent support for mixed TCP/IP and UUCP sites
- was a major selling point for it, but as UUCP has declined, so has
- smail. Also, smail is less efficient than sendmail on high-volume
- connections.
-
-
- As with sendmail, it is unlikely that you will need to tweak a
- preinstalled smail configuration.
-
- (Very occasionally you might run across references to an `smail 2.5'.
- This program has been obsolete for a long time. Don't bother with
- it.)
-
-
- 5.3. qmail
-
- The qmail program is a sendmail-compatible MTA designed specifically
- for high security. The author has a standing reward of $500 for
- publication of the first verifiable security hole; this reward has
- gone unclaimed since March 1997.
-
- The qmail home page is at < http://pobox.com/~djb/qmail.html>.
-
-
- 5.4. exim
-
- The exim program is similar to smail3, but with more features. It
- advertises particular strengths in spam-blocking and support of
- several virtual hosts (virtual DNS domains) on the same host.
-
- The exim home page is at < http://www.exim.org/>.
-
- I tried it on my own computer, it looks like a nice merge between
- smail configuration system and qmail security, moreover it has the
- advantage of being GPL.
-
- A section explaining how to replace your current MTA by exim will be
- added soon.
-
-
- 6. Installing Transport Software
-
-
-
- 6.1. Qmail v1.03
-
-
- Secured, fast and easy to use, this is my preferred MTA (mail
- transport agent).
-
- Currently, no distribution comes with qmail preinstalled. We will
- focus on compiling and installing qmail, since this is the only tricky
- part: configuration is really straightforward.
-
-
- 6.1.1. Getting qmail
-
-
- Go to www.qmail.org to download the latest version.
-
-
- 6.1.2. Uncompressing sources
-
-
- Then decompress it by running:
-
-
- mv qmail.tar.gz /usr/local/src
- cd /usr/local/src ; tar -zxvf qmail.tar.gz
-
-
-
- If you find a bz2 version (new and better compression format), just
- replace tar with:
- bunzip2 qmail.tar.bz2
- tar -xvf qmail.tar
-
-
-
- 6.1.3. Preparing for compilation
-
-
- Now enter the qmail directory to examine the configuration defaults:
-
-
- cd qmail; more conf-*
-
-
-
- You shouldn't need to change any defaults, but you could (for example)
- specify an alternate installation directory or better compilation
- flags.
-
- Now run:
-
-
- mkdir /var/qmail
-
-
-
- to create target dir.
-
- If you haven't installed a Debian distribution, you'll need to add
- several user IDs for qmail's use: qmail's high security depends on
- that.
-
- The fact that qmail is divided into modules running each under their
- own UID makes it much harder for an intruder to break your whole mail
- system or gain root access by abusing it.
-
- So run:
-
-
- # groupadd nofiles
- # useradd -g nofiles -d /var/qmail/alias alias
- # useradd -g nofiles -d /var/qmail qmaild
- # useradd -g nofiles -d /var/qmail qmaill
- # useradd -g nofiles -d /var/qmail qmailp
- # groupadd qmail
- # useradd -g qmail -d /var/qmail qmailq
- # useradd -g qmail -d /var/qmail qmailr
- # useradd -g qmail -d /var/qmail qmails
-
-
-
- or hand-edit /etc/passwd and /etc/group to add these users by
- yourself.
-
- Evan E. reported he had to use "-g groupid" parameter for a vanilla
- groupadd (Caldera 1.2), else groupadd reported this error : "A group
- with that name already exists."
-
- For example you can respectively add:
-
-
- qmail:*:2107:
- nofiles:*:2108:
-
-
-
- &
-
-
-
- alias:*:7790:2108::/var/qmail/alias:/bin/true
- qmaild:*:7791:2108::/var/qmail:/bin/true
- qmaill:*:7792:2108::/var/qmail:/bin/true
- qmailp:*:7793:2108::/var/qmail:/bin/true
- qmailq:*:7794:2107::/var/qmail:/bin/true
- qmailr:*:7795:2107::/var/qmail:/bin/true
- qmails:*:7796:2107::/var/qmail:/bin/true
-
-
-
- Now you can run
-
-
- make setup check
-
-
-
- to check your configuration, then :
-
-
- ./config
-
-
-
- to configure qmail.
-
- Attention, your server has to be resolvable by DNS or ./config will
- get confused.
-
- If you don't have DNS access, you can give your server name directly
- via :
-
-
- ./config-fast foo.bar.com
-
-
-
- Now you must install some aliases, since /etc/alias is not used by
- qmail unless you compile and install an optional package.
-
- Here's my setup :
-
-
-
- File : ".qmail-MAILER-DAEMON"
- &postmaster
- File : ".qmail-bin"
- &root
- File : ".qmail-daemon"
- &root
- File : ".qmail-decode"
- &root
- File : ".qmail-dumper"
- &root
- File : ".qmail-games"
- &root
- File : ".qmail-ingres"
- &root
- File : ".qmail-mailer-daemon"
- &postmaster
- File : ".qmail-manager"
- &root
- File : ".qmail-news"
- &root
- File : ".qmail-nobody"
- &root
- File : ".qmail-operator"
- &root
- File : ".qmail-postmaster"
- &root
- File : ".qmail-root"
- &guylhem
- File : ".qmail-system"
- &root
- File : ".qmail-toor"
- &root
- File : ".qmail-uucp"
- &root
- File : ".qmail-uucp-default"
- |preline -dr /usr/bin/uux - -r -gC -a"${SENDER:-MAILER-DAEMON}" lm!rmail "($DEFAULT@$HOST)"
-
-
-
- You need to create each of these file in ~alias, replacing &guylhem in
- .qmail-root by your own login to get root mail.
-
- ATTENTION UUCP USERS !
-
- DO NOT TRUST THE QMAIL FAQ FOR UUCP, USE MY .qmail-uucp-default
- INSTEAD! ELSE YOU WILL NOT BE ABLE TO SEND ANY MAIL BY YOUR UUCP
- CONNEXION!
-
- Now you'll need to decide in which format your users will get their
- mail.
-
- Here's my suggestion :
-
- · For NFS mounted home dirs, use MAILDIR format with a patch for
- local mail readers (patchs are available on www.qmail.org)
-
- · If no patch is available, prefer MAILFILE format : any mail reader
- can read a file containing mail, people will only need to create an
- alias (for bash) or a setenv (for csh) for their mail reader
-
- · Avoid /var/spool/mail/$USER format, too insecure
-
- To fix the default format, read each file in /var/qmail/boot then copy
- the one you best like to /var/qmail/rc.
-
- home or proc are safe choices, but prefer home for security reasons.
-
-
- 6.1.4. Configuring qmail
-
-
- In /var/qmail/control, edit:
-
-
- 6.1.4.1. defaultdomain, me, plusdomain
-
-
-
- · me is you local FQDN (full qualified domain name), for example on
- my machine it is barberouge.linux.lmm.com
-
- · defaultdomain will be added to any host name without dots,
- including defaulthost, for example you can set it to localnetwork
- so any mail sent to joe@hisbox will be completed to be sent to
- joe@hisbox.localnetwork instead
-
- · plusdomain is the exception: it is added to any host name that ends
- with a plus sign, including defaulthost (set in me) if it ends with
- a plus sign.
-
- These 3 examples show you the power and ease of configuration of
- qmail!
-
-
- 6.1.4.2. locals, rcpthosts
-
-
- If you want to support virtual domain names, just put additional names
- in these files. Any mail you receive for these names will be handled
- locally.
-
- The difference between locals and rcpthosts is the latter isn't
- considered as a local alias, which is useful if you receive mail from
- some free email address like yahoo.com or lemel.fr while you also send
- mail to other users of these non local services, i.e. you don't want
- to handle locally mail send to someone@yahoo.com!
-
-
- 6.1.4.3. virtualdomains
-
-
- There can you specify default outgoing mode, for example :
-
-
- #:alias-uucp
-
-
-
- if you don't want to send outgoing mail by uucp but by smtp (default)
- or
-
-
- :alias-ucp
-
-
-
- if you send your outgoing mail by uucp.
-
-
- 6.1.5. Testing qmail
-
-
- Now it is configured, try:
-
-
- sh -cf '/var/qmail/rc &'
-
-
-
- to launch qmail (it won't interfere with your local MTA), then:
-
-
-
- echo to: mylogin | /var/qmail/bin/qmail-inject
-
-
-
- You should receive this mail in the format you've chosen in
- /var/qmail/boot/.
-
-
- 6.1.6. Removing your other MTA
-
-
- If this test was successful, just kill your previous MTA:
-
- killall -STOP daemon_name ; if any children are running, you should
- killall -CONT their_name, wait, killall -STOP again, and repeat ad
- nauseam.
-
- If there aren't any children, killall -TERM and then killall -CONT.
-
- Remove it (how you can do this depends on the distribution you
- installed, for example rpm -e --nodeps on RedHat, Caldera and Suse, or
- dpkg -r --force-depends on Debian) then run:
-
-
- # ln -s /var/qmail/bin/sendmail /usr/lib/sendmail
- # ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail
-
-
-
- Now set up qmail-smtpd in /etc/inetd.conf (all on one line):
-
-
- smtp stream tcp nowait qmaild /var/qmail/bin/tcp-env tcp-env /var/qmail/bin/qmail-smtpd
-
-
-
- If you are using a old non-SYSV-init distribution like redhat, just
- add to your boot scripts:
-
-
- sh -cf '/var/qmail/rc &'
-
-
-
- Usually this should be /etc/rc.local but your mileage may vary.
-
-
- For actual SYSV-init compliant distributions (RedHat, Caldera, Suse,
- Debian), add this script to /etc/init.d/ or /etc/rc.d/init.d/ :
-
- DEBIAN version:
-
-
-
- #!/bin/sh
-
- test -x /var/qmail/rc || exit 0
-
- case "$1" in
- start)
- echo -n "Starting mta: "
- sh -cf '/var/qmail/rc &'
- echo "qmail."
- ;;
- stop)
- echo -n "Stopping mta: "
- killall qmail-lspawn
- echo "qmail."
- ;;
- restart)
- echo -n "Restarting mta: "
- killall -HUP qmail-lspawn
- killall -ALRM qmail-lspawn
- echo "qmail."
- ;;
- *)
- echo "Usage: /etc/init.d/qmail {start|stop|restart}"
- exit 1
- esac
-
- exit 0
-
-
-
- REDHAT version:
-
-
-
- #!/bin/sh
- #
- # qmail This shell script takes care of starting and stopping qmail.
- #
- # description: qmail is a Mail Transport Agent, which is the program \
- # that moves mail from one machine to another.
- # processname: qmail
- # config: /var/qmail/control/
-
- # Source function library.
- . /etc/rc.d/init.d/functions
-
- # Source networking configuration.
- . /etc/sysconfig/network
-
- export PATH=$PATH:/var/qmail/bin
-
- # Check that networking is up.
- [ ${NETWORKING} = "no" ] && exit 0
-
- [ -f /usr/sbin/sendmail ] || exit 0
-
- # See how we were called.
- case "$1" in
- start)
- # Start daemons.
- echo -n "Starting qmail: "
- qmail-start '|preline procmail' splogger qmail &
- touch /var/lock/subsys/qmail
- echo
- ;;
- stop)
- # Stop daemons.
- echo -n "Shutting down qmail: "
- killproc qmail-lspawn
- echo
- rm -f /var/lock/subsys/qmail
- ;;
- restart)
- $0 stop
- $0 start
- ;;
- status)
- status qmail
- ;;
- *)
- echo "Usage: qmail {start|stop|restart|status}"
- exit 1
- esac
-
- exit 0
-
-
-
- And make symlinks to each /etc/rc.d/rcN.d/, for example:
-
-
- ln -sf /etc/init.d/qmail /etc/rc1.d/K19qmail
-
-
-
- If the first letter is K, you will kill qmail on this runlevel (1 for
- single mode or 6 for boot), but if the first letter is S, you will
- start qmail on this runlevel (each others runlevel).
- · How to decide whether you should put a K or a S? Do what the
- majority of dæmons in this runlevel do!
-
- · What number should you put after K or S? The number next to your
- network daemon.
-
- That means the MTA will be started and stopped respectively after
- and before the network daemon.
-
- Without this, your network will be unreachable while the MTA would
- expect it to work.
-
- RedHat, Caldera and Suse will use /etc/rc.d/ instead of plain /etc/
- for Debian distribution, i.e. /etc/rc.d/rc1.d or /etc/rc.d/init.d for
- example.
-
-
- 6.1.7. That's all, folks!
-
-
- No need to reboot (remember, you're using linux, not some other cheap
- OS!) for the modifications to take effect, just run:
-
-
-
- killall inetd
- init 1
-
-
-
- To go to single user mode, then:
-
-
- init 2
-
-
-
- to go back to your default runlevel (indicated in /etc/inittab with
- initdefault label).
-
- You could also hand-start qmail script but "init" method will show you
- if qmail script is well positioned, i.e. launched after network
- scripts but before any program which depends on email to warn you
- (like inn).
-
-
- 6.2. Smail v3.1
-
-
- Smail3.1 seems to be a de-facto standard transport agent for uucp-only
- sites and for some smtp sites. It's easy to configure, it compiles
- without patching from the sources and it's fairly secure.
-
-
- 6.2.1. Configuring smail
-
-
- Install the smail binary from your distribution (I recommend you
- choose this) or get the smail sources and build smail. If you're
- building smail from sources, you need to have the following in your
- os/linux file so that 'sed' gives you shell scripts that work
- properly.
-
-
- CASE_NO_NEWLINES=true
-
-
-
- Once it's installed, config. files will certainly go in /etc/smail
- (but your mileage may vary if you use old distributions); let's start
- editing them!
-
-
- 6.2.1.1. "config" file
-
-
-
- # From
- smart_path=polux
- smart_transport=uux
-
- # To
- hostname=barberouge
- domains=linux.lmm.com
-
- visible_name=barberouge.linux.lmm.com
- uucp_name=barberouge.linux.lmm.com
-
- # max_message_size=512k
- # auth_domains=foo.bar
- # more_hostnames=barberouge.polux.freenix.fr
-
-
-
- Well, first, who is feeding you? I'm fed by "polux" via uucp (i.e.
- uux transport); naturally you need to change this file according to
- your own situation. For example, you could by fed by
- "bargw.bar.foobar.com" via "smtp", in that case you don't need a
- transport file and can define "-transport_file " to indicate you don't
- need one.
-
- You can also use "postmaster_address = yourname", hide the network
- topology in outgoing addresses (if you're a gateway) using
- "visible_name", set which aliases address can also be used for the
- email you receive, using "more_hostnames".
-
- See smail documentation for more details or the examples in
- /usr/doc/smail/examples to see if any match your situation.
-
-
- 6.2.1.2. "directors" file
-
-
-
- # aliasinclude - expand ":include:filename" addresses produced by alias files
- # This entry and the next one are pretty much boiler-plate. Reasons
- # for making significant changes are few. The sole purpose of these
- # is to match and expand addresses of the form:
- # :include:pathname
- # which may occur in alias files or mailing-list/forward files
- # (produced by any director with a driver of forwardfile).
- aliasinclude:
- driver = aliasinclude, # use this special-case driver
- nobody; # associate nobody user with addresses
- # when mild permission violations
- # are encountered
- copysecure, # get permissions from alias director
- copyowners, # get owners from alias director
-
-
-
- # forwardinclude - expand ":include:filename" addrs produced by forward files
- forwardinclude:
- driver = forwardinclude, # use this special-case driver
- nobody;
- copysecure, # get perms from forwarding director
- copyowners, # get owners from forwarding director
-
-
- # aliases - search for alias expansions stored in a database
- # This is the standard aliases file. It is used for generic things,
- # like mapping root, postmaster, MAILER-DAEMON and uucp to site
- # admins, creating some small system alias expansions, and such. In
- # this site configuration, the aliases file is used mostly for
- # machine-specific aliasing/forwarding information. Global forwarding
- # information should be put in the "forward" database.
- aliases:
- driver=aliasfile, # general-purpose aliasing director
- -nobody, # all addresses are associated
- # with nobody by default, so setting
- # this is not useful.
- sender_okay, # don't remove sender from expansions
- owner=owner-$user; # problems go to an owner address
- file=/etc/aliases,
- modemask=002, # should not be globally writable
- optional, # ignore if file does not exist
- proto=lsearch, # unsorted ASCII file
-
-
- # forward - search for expansions stored in a forwarding database
- # This is the subdomain-wide user forwarding database. Entries are
- # maintained here for current or past users, to forward their mail to
- # their preferred mail-reading machine. The forward database is
- # shipped around the TCP/IP network as changes are made, to keep the
- # network consistent.
- #forward:
- # driver = aliasfile, # general-purpose aliasing director
- # -nobody, # all addresses are associated
- # # with nobody by default, so setting
- # # this is not useful.
- # owner = real-$user; # problems go to an owner address
- #
- # file = /etc/forward,
- # modemask = 002,
- # proto = dbm, # use dbm(3X) library for access
-
-
- # dotforward - expand .forward files in user home directories
- # For users that have an entry in the "forward" database, a ".forward"
- # file is only used if it is on the "home" machine, as identified in
- # the forward database. If used, it is treated as a list of addresses
- # to which mail should be delivered, rather than (or in addition to)
- # the user identified in the local address.
- dotforward:
- driver = forwardfile, # general-purpose forwarding director
- owner = postmaster, nobody, sender_okay;
-
- file = ~/.forward, # .forward file in home directories
- checkowner, # the user can own this file
- owners = root, # or root can own the file
- modemask = 002, # it should not be globally writable
- caution = daemon:root, # don't run things as root or daemon
- # be extra careful of remotely accessible home directories
- unsecure = "~uucp:/tmp:/usr/tmp:/var/tmp"
-
-
- # forwardto - expand a "Forward to " in user mailbox files
- # This emulates the V6/V7/System-V forwarding mechanism which uses a
- # line of forward addresses stored at the beginning of user mailbox files
- # prefixed with the string "Forward to "
- forwardto:
- driver = forwardfile,
- owner = postmaster, nobody, sender_okay;
-
- file = /var/spool/mail/${lc:user}, # point at user mailbox files
- forwardto, # enable "Forward to " function
- checkowner, # the user can own this file
- owners = root, # or root can own the file
- modemask = 0002, # under System V, group mail can write
- caution = daemon:root # don't run things as root or daemon
-
-
- # user - match users on the local host with delivery to their mailboxes
- user: driver = user; # driver to match usernames
- transport = local # local transport goes to mailboxes
-
-
- # real_user - match usernames when prefixed with the string "real-"
- # This is useful for allowing an address which explicitly delivers to a
- # user's mailbox file. For example, errors in a .forward file expansion
- # could be delivered here, or forwarding loops between multiple machines
- # can be resolved by using a real-username address. Also, users that
- # wish to use mail as a means of transferring data to a machine that
- # is not their "home" machine can mail to real-login-name@remote.host.
- real_user:
- driver = user;
- transport = local,
- prefix = "real-" # for example, match real-root
-
-
- # lists - expand mailing lists stored in a list directory
- # mailing lists can be created simply by creating a file in the
- # /etc/smail/lists directory.
- lists: driver = forwardfile,
- caution, # flag all addresses with caution
- nobody, # and then associate the nobody user
- owner = owner-$user; # system V sites may wish to use
- # o-$user, as owner-$user may be
- # too long for a 14-char filename.
- file = lists/${lc:user} # lists is under $smail_lib_dir
-
-
- # owners - expand mailing lists stored in a list owner directory
- # mailing lists owner lists can be created simply by creating a file
- # in the /etc/smail/lists/owner directory. Mailing list owners
- # are sent locally generated errors dealing with a mailing list of the
- # same name. To create an owner list for a mailing list, create a
- # file with the name of the list in /etc/smail/lists/owner. This
- # will create a list address of owner-listname, as is used by the
- # "lists" director above.
- owners: driver = forwardfile,
- caution, # flag all addresses with caution
- nobody, # and then associate the nobody user
- owner = postmaster; # system V sites may wish to use
- # o-$user, as owner-$user may be
- # too long for a 14-char filename.
- prefix = "owner-",
- file = lists/owner/${lc:user} # lists is under $smail_lib_dir
-
-
- # request - expand mailing lists stored in a list request directory
- # mailing lists request lists can be created simply by creating a file
- # in the /etc/smail/lists/request directory. Request addresses
- # are typically used as a standard address for queries about a mailing
- # list. For example, requests for additions or deletions to a list
- # will generally be sent to "list-request", which should be set up to
- # forward to the appropriate person or persons.
- request: driver = forwardfile,
- caution, # flag all addresses with caution
- nobody, # and then associate the nobody user
- owner = postmaster; # system V sites may wish to use
- # o-$user, as owner-$user may be
- # too long for a 14-char filename.
- suffix = "-request",
- file = lists/request/${lc:user} # lists is under $smail_lib_dir
-
-
-
- You shouldn't need to change anything here, only mailing list options
- if you intend to run some using smail, or forwards options if, for
- example, you want to disable forwarding.
-
-
- 6.2.1.3. "fidopaths" file
-
-
-
- .f105.n324.z2.fidonet.org f105.n324.z2.fidonet.org!%s
- .n324.z2.fidonet.org f105.n324.z2.fidonet.org!%s
- .z2.fidonet.org f105.n324.z2.fidonet.org!%s
- .fidonet.org f105.n324.z2.fidonet.org!%s
-
-
-
- Create such a file only if you're using ifmail and FIDO.
-
-
- 6.2.1.4. "routers" file
-
-
-
- # forces - force certain paths
- # This database exists as a means of hardcoding the paths to various
- # machines or domains. It is for use in creating temporary tweaks to
- # the other routing databases. To change the database, edit the file
- # maps/force.path and type "make" in the maps/ subdirectory.
- forces:
- driver = pathalias, # router to search paths file
- method = /etc/smail/maps/table; # transports are in this file
- file = forcepaths, # file containing force path info
- proto = lsearch, # use the sorted path file
- optional,
- reopen # close when not being used
-
-
- uucp_neighbors:
- driver=uuname, # use a program which returns neighbors
- transport=uux;
- cmd="/usr/bin/uuname -a", # specifically, use the uuname program
- # domain=uucp # strip ending ".uucp"
-
-
- # smart_host - a partially specified smarthost director
- # If the config file attribute smart_path is defined as a path from the
- # local host to a remote host, then hostnames not matched otherwise will
- # be sent off to the stated remote host. The config file attribute
- # smart_transport can be used to specify a different transport.
- # If the smart_path attribute is not defined, this router is ignored.
- smart_host:
- driver = smarthost, # special-case driver
- transport = uux # by default deliver over UUCP
- # path=phreak
-
-
- # ifmail - to send mails to fidonet and vice versa
- ifmail:
- driver=pathalias,
- transport=ifmail;
- file=fidopaths,
- proto=lsearch
-
-
-
- You should only include ifmail chapter if you use ifmail for FIDO
- mails. Note you can also change transport mode from "uux" (ie UUCP)
- to, for example, "smtp" or even 'hardcode the paths to various
- machines or domains' in "/etc/smail/maps/table".
-
- This is useful if you want outgoing mail for your local network to be
- delivered immediately, since there's no need for it to be routed to
- your uucp connexion of your internet access.
-
-
- 6.2.1.5. "transports" file
-
-
-
- # local - deliver mail to local users
- # Tell smail to append directly to user mailbox files in the /var/spool/mail
- # directory.
- #local: driver = appendfile, # append message to a file
- # -return_path, # include a Return-Path: field
- # local, # use local forms for delivery
- # from, # supply a From_ envelope line
- # unix_from_hack; # insert > before From in body
- #
- # file = /var/spool/mail/${lc:user}, # use this location for Linux
- # # Note, mail spool must be 1777
- # file = ~/mailfile, # use this location for better security
- # group = mail, # group to own file for System V
- # mode = 0660, # under System V, group mail can access
- # suffix = "\n", # append an extra newline
- # append_as_user,
-
-
- # This allows each user to have a ~/.procmailrc file to control filtering
- # of mail and saving mail from mail lists in separate mailboxes if they wish.
- local: +inet,
- -uucp,
- driver = pipe, # append message to a file
- return_path, # include a Return-Path: field
- local, # use local forms for delivery
- from, # supply a From_ envelope line
- unix_from_hack; # insert > before From in body
-
- cmd = "/usr/bin/procmail", # use procmail for local delivery
- parent_env, # environment info from parent addr
- pipe_as_user, # use user-id associated with address
- umask = 0022, # umask for child process
- # -ignore_status, # exit status should be believed
- # -ignore_write_errors, # retry on broken pipes
-
-
- # pipe - deliver mail to shell commands
- # This is used implicitly when smail encounters addresses which begin with
- # a vertical bar character, such as "|/usr/lib/news/recnews talk.bizarre".
- # The vertical bar is removed from the address before being given to the
- # transport.
- #pipe: driver = pipe, # pipe message to another program
- # return_path, local, from, unix_from_hack;
- #
- # cmd = "/bin/sh -c $user", # send address to the Bourne Shell
- # parent_env, # environment info from parent addr
- # pipe_as_user, # use user-id associated with address
- # umask = 0022, # umask for child process
- # -log_output, # do not log stdout/stderr
- # ignore_status, # exit status may be bogus, ignore it
- # ignore_write_errors, # ignore broken pipes
-
-
- # file - deliver mail to files
- # This is used implicitly when smail encounters addresses which begin with
- # a slash or squiggle character, such as "/usr/info/list_messages" or
- # perhaps "~/Mail/inbox".
- #file: driver = appendfile,
- # return_path, local, from, unix_from_hack;
- #
- # file = $user, # file is taken from address
- # append_as_user, # use user-id associated with address
- # expand_user, # expand ~ and $ within address
- # check_path,
- # suffix = "\n",
- # mode = 0644
- # uux - deliver to the rmail program on a remote UUCP site
- #
- # As many as five recipient addresses will be delivered to the remote
- # host in one UUCP transaction.
- uux: driver = pipe,
- -uucp,
- inet,
- # uucp, # use UUCP-style addressing forms
- from, # supply a From_ envelope line
- max_addrs = 5, # at most 5 addresses per invocation
- max_chars = 200; # at most 200 chars of addresses
- # the -r flag prevents immediate delivery, parentheses around the
- # $user variable prevent special interpretation by uux.
- cmd = "/usr/bin/uux - -r -g$grade $host!rmail $((${strip:user})$)",
- # cmd="/usr/bin/uux - $host!rmail $(($user)$)",
- ignore_write_errors, # ignore broken pipes
- umask = 0022,
- # pipe_as_sender,
-
-
- # uux_one_addr - deliver mail over UUCP to a remote host that can take
- # one address at a time.
- # This is often necessary when delivering to a site running an unmodified
- # version of 4.1BSD.
- uux_one_addr:
- driver = pipe,
- uucp, # use UUCP-style addressing forms
- from; # supply a From_ envelope line
- # the -r flag prevents immediate delivery
- cmd = "/usr/bin/uux - -r -g$grade $host!rmail (${strip:user})",
- umask = 0022,
- pipe_as_sender
-
-
- queueonly:
- driver = pipe; # send the message to a pipe
- cmd = "/usr/lib/sendmail -Q -f $sender -bm $user",
- # use getmail for local delivery
- user=root, # execute getmail as "root"
- group=mail, # execute getmail as "mail"
- parent_env, # environment info from parent addr
- -pipe_as_user, # use user-id associated with address
- umask = 0007, # umask for child process
-
- # to deliver the message. The smtp transport is included only if BSD
- # networking exists.
- # The uucp attribute can be specified for transfers within the UUCP
- # zone. The inet attribute must be specified for transfers within the
- # Internet.
- # NOTE: This is hardly optimal, a backend should exist which can handle
- # multiple messages per connection.
- # ALSO: It may be necessary to restrict max_addrs to 100, as this is the
- # lower limit SMTP requires an implementation to handle for one
- # message.
- smtp: driver=tcpsmtp,
- inet, # if UUCP_ZONE is not defined
- # uucp, # if UUCP_ZONE is defined
- -max_addrs, -max_chars; # no limit on number of addresses
-
- short_timeout=5m, # timeout for short operations
- long_timeout=2h, # timeout for longer SMTP operations
- service=smtp, # connect to this service port
- # For internet use: uncomment the below 4 lines
- use_bind, # resolve MX and multiple A records
- defnames, # use standard domain searching
- defer_no_connect, # try again if the nameserver is down
- local_mx_okay, # fail an MX to the local host
-
-
- ifmail:
- from,received,max_addrs=5,max_chars=200,
- driver=pipe;
- pipe_as_sender,
- cmd="/usr/local/bin/ifmail -x9 -r$host $((${strip:user})$)"
-
-
-
- You should include an ifmail chapter only if you use ifmail for FIDO
- mail. Apart from that, you shouldn't need to edit anything in this
- file which defines transport agents (like uux, smtp ...) you can use
- as parameters in other config. files.
-
- Note I commented out some parts, like "pipes" or "file", to enhance
- security.
-
-
- 6.2.1.6. "maps/" directory
-
-
- It contains map and table files:
-
- First, map file
-
-
-
- #N foo.bar foo2.bar2
- #S AT 486/RedHat Linux 1.2.13
- #O organization
- #C contact
- #E administration (email)
- #T phone
- #P address
- #R
- #U hosts connected via uucp
- #W created/edited by
- #
- hname polux
-
- hname linux.eu.org
-
- hname = polux
- hname = polux.linux.eu.org
-
-
-
- Once again, edit this file to match you situation (I'm fed by
- polux.linux.eu.org).
-
- Now table file
-
-
-
- * uux
-
-
-
- You can define different transports to different paths, for example
- "smtp" for the machines in your local network, "uux" (i.e. uucp) for
- the rest of the world or vice-versa (I'm using uucp for any outgoing
- mail, therefore I use "*"!).
-
-
- 6.2.2. Other good examples
-
-
- The previous files are the one I currently use for my site, you
- shouldn't encounter any problem using them as samples/basis for your
- own files.
-
- The following files are provided only as good examples to configure
- smail a different way.
-
-
-
- #ident "@(#) transports,v 1.2 1990/10/24 05:20:46 tron Exp"
-
- # See smail(5) for a complete description of the contents of this file.
-
- # local - deliver mail to local users
- #
- # Tell smail to append directly to user mailbox files in the /usr/mail
- # directory.
- local: driver = appendfile, # append message to a file
- return_path, # include a Return-Path: field
- local, # use local forms for delivery
- from, # supply a From_ envelope line
- unix_from_hack; # insert > before From in body
-
- file = /usr/mail/${lc:user}, # use this location for System V
- group = mail, # group to own file for System V
- mode = 0660, # under System V, group mail can access
- suffix = "\n", # append an extra newline
- append_as_user,
-
- # pipe - deliver mail to shell commands
- #
- # This is used implicitly when smail encounters addresses which begin with
- # a vertical bar character, such as "|/usr/lib/news/recnews talk.bizarre".
- # The vertical bar is removed from the address before being given to the
- # transport.
- pipe: driver = pipe, # pipe message to another program
- return_path, local, from, unix_from_hack;
-
- cmd = "/bin/sh -c $user", # send address to the Bourne Shell
- parent_env, # environment info from parent addr
- pipe_as_user, # use user-id associated with address
- umask = 0022, # umask for child process
- -log_output, # do not log stdout/stderr
- ignore_status, # exit status may be bogus, ignore it
- ignore_write_errors, # ignore broken pipes
-
- # file - deliver mail to files
- #
- # This is used implicitly when smail encounters addresses which begin with a
- # slash or squiggle character, such as "/usr/info/list_messages" or perhaps
- # "~/Mail/inbox".
- file: driver = appendfile,
- return_path, local, from, unix_from_hack;
-
- file = $user, # file is taken from address
- append_as_user, # use user-id associated with address
- expand_user, # expand ~ and $ within address
- suffix = "\n",
- mode = 0644
-
- # uux - deliver to the rmail program on a remote UUCP site
- #
- # As many as five recipient addresses will be delivered to the remote host in
- # one UUCP transaction.
- uux: driver = pipe,
- uucp, # use UUCP-style addressing forms
- from, # supply a From_ envelope line
- max_addrs = 5, # at most 5 addresses per invocation
- max_chars = 200; # at most 200 chars of addresses
-
- # the -r flag prevents immediate delivery, parentheses around the
- # $user variable prevent special interpretation by uux.
- cmd = "/usr/bin/uux - -r -g$grade $host!rmail $((${strip:user})$)",
- umask = 0022,
- pipe_as_sender
- # uux_one_addr - deliver mail over UUCP to a remote host that can take one
- # address at a time.
- #
- # This is often necessary when delivering to a site running an unmodified
- # version of 4.1BSD.
- uux_one_addr:
- driver = pipe,
- uucp, # use UUCP-style addressing forms
- from; # supply a From_ envelope line
-
- # the -r flag prevents immediate delivery
- cmd = "/usr/bin/uux - -r -g$grade $host!rmail (${strip:user})",
- umask = 0022, pipe_as_sender
-
- # demand - deliver to a remote rmail program, polling on demand
- demand: driver = pipe,
- uucp, from, max_addrs = 5, max_chars = 200;
-
- # with no -r flag, try to contact remote site immediately
- cmd = "/usr/bin/uux - -g$grade $host!rmail $(($user)$)",
- umask = 0022, pipe_as_sender
-
- # uusmtp - deliver to the rsmtp program on a remote UUCP site
- #
- # Deliver using a simple Batched SMTP protocol to the remote machine.
- # This allows much more arbitrary addresses to be used. It also
- # removes the limit on recipient addresses per invocation of uux.
- uusmtp: driver = pipe,
- bsmtp, # send batched SMTP commands
- -max_addrs, # there is no limit on the number or
- -max_chars; # total size of recipient addresses.
-
- # supply -r to prevent immediate delivery, the recipient addresses
- # are stored in the data sent to the standard input of rsmtp.
- cmd = "/usr/bin/uux - -r -g$grade $host!rsmtp",
- umask = 0022, pipe_as_sender
-
- # demand_uusmtp - deliver to a remote rsmtp program, polling on demand
- demand_uusmtp:
- driver = pipe,
- bsmtp, -max_addrs, -max_chars;
-
- # with no -r flag, try to contact remote site immediately
- cmd = "/usr/bin/uux - -g$grade $host!rsmtp",
- umask = 0022, pipe_as_sender
-
- # smtp - deliver using SMTP over TCP/IP
- #
- # Connect to a remote host using TCP/IP and initiate an SMTP conversation to
- # deliver the message. The smtp transport is included only if BSD networking
- # exists.
-
- # NOTE: It may be necessary to restrict max_addrs to 100, as this is the
- # lower limit SMTP requires an implementation to handle for one
- # message.
- smtp: driver = smtp,
- -max_addrs,
- -max_chars
-
-
-
- #ident "@(#) table,v 1.2 1990/10/24 05:20:31 tron Exp"
-
- # This file names the transports that are to be used in delivering
- # to specific hosts from bargw.
-
- #host transport
- #-------- ---------
- curdsgw demand_uusmtp # deliver using batched SMTP
- oldbsd uux_one_addr # 4.1BSD sites cannot take more than one addr
- sun demand # call sun when their is mail to send
- * uux # for all others, poll at intervals
-
-
-
- 6.2.3. Restarting inetd
-
-
- To run smail as a smtp daemon, add one of the following to
- /etc/inetd.conf:
-
- smtp stream tcp nowait root /usr/bin/smtpd smtpd
-
- or:
-
- smtp stream tcp nowait root /usr/sbin/tcpd /usr/sbin/in.smtpd
-
-
-
- Outgoing mail gets sent automatically, when using elm.
-
-
- 6.2.4. Smail with smtp
-
-
- Generally, ISPs use smtp, therefore you shouldn't have any problems
- sending your mail. If your internet link is down when you send mail,
- then the mail sits in "/var/spool/smail/input". When the link next
- comes up, "runq" is run which causes the mail to be sent. However,
- receiving mail is the problem since your provider has many clients to
- look after, not only you!
-
- Usually, you can retrieve your mail via the POP protocol, see POP
- section below.
-
-
- 6.3. OUTDATED SECTION: Sendmail+IDA
-
-
- For big sites, sendmail is worth choosing, due to the "incredible ease
- of use", (very relative feeling when you know qmail) but you must
- decide which you want between sendmail+IDA and sendmail 8.x:
-
-
- · If you use an old kernel (1.0): sendmail+IDA
-
- · If you use a not so old kernel (1.2): sendmail+IDA and source code
- editing
-
- · Recent kernel (2.0) will choose sendmail 8.x
-
- Remember, linux newbies or people concerned by security / ease of
- configuration should rather try using smail or qmail, which are easier
- to use and safer.
- 6.3.1. Source installation
-
-
- If your distribution doesn't provide you with a ready-to-install
- sendmail package (.rpm for RedHat, Caldera and Suse, .deb for Debian)
- just download the sources and run:
-
-
- · cd / ; tar -zxvf sendmail5.67b+IDA1.5.tgz
-
-
- · cd to /usr/local/lib/mail/CF and copy the sample.m4 local.m4 file
- to "yourhostname.m4".
-
- Edit out the distributed hostname, aliases, smarthost and put in the
- correct one for your site. The default file is for a uucp-only site
- (no longer in 8.x) who has domainized headers and who talks to a smart
- host. Then "make yourhostname.cf" and move the resulting file to
- /etc/sendmail.cf
-
-
- · if you are uucp-only, you do *NOT* need to create any of the tables
- mentioned in the README.linux file.
-
- You'll just have to touch the files so that the Makefile works. Just
- edit the .m4 file, make sendmail.cf and start testing it.
-
-
- · if you're uucp-only and you talk to sites in addition to your
- "smart-host", you'll need to add uucpxtable entries for each (or
- mail to them will also go through the smart host) and run dbm
- against the revised uucpxtable.
-
-
- · If you run Rich Braun's original binary distribution of 5.67a,
- you'll need to freeze the configuration if you change your .cf file
- with "/usr/lib/sendmail -bz" to make the changes take effect.
-
- You should also update your version to at least 5.67b since there is a
- nasty security hole in 5.67a and earlier. Another nice thing is that
- if you have mail.debug set and you run syslogd, your incoming and
- outgoing mail messages will get logged. See the "/etc/syslog.conf"
- file for details.
-
- The sources for sendmail+IDA can be found at vixen.cso.uiuc.edu ; they
- require no patching to run under Linux if you're running something
- like a kernel of 1.00.
-
- If you're running a kernel > 1.1.50, you get the fun of reversing most
- of the Linux-specific patches that are now in the vanilla sources. (I
- *did* told you this sendmail was only for old kernels:-)
-
- It's extremely obvious where this needs to be done: just type "make"
- and when it blows up, go to that line in the sources and comment out
- the Linux-specific code that's in there.
-
- If you're going to run sendmail+IDA, I strongly recommend you go to
- the sendmail5.67b+IDA1.5 version since all required Linux-specific
- patches are now in the vanilla sources and several security holes have
- been plugged that WERE (!!!) in the older version you may have grabbed
- or built before about December 1st, 1993.
-
- Now linux kernel is 2.0, you should use sendmail 8.x instead of
- sendmail+IDA, but I already told you'd better choose sendmail 8.x:-)
-
-
- 6.3.2. The sendmail.m4 file
-
-
- Sendmail+IDA requires you to set up a sendmail.m4 file rather than
- editing the sendmail.cffile directly. The nice thing about this is
- that it is simple to set up mail configurations that are extremely
- difficult (if not totally impossible for most people to set up
- correctly) in smail or traditional sendmail.
-
- The sendmail.m4 file that corresponds to the above smail example looks
- like the following:
-
-
- dnl #------------------ SAMPLE SENDMAIL.M4 FILE ------------------
- dnl #
- dnl # (the string 'dnl' is the m4 equivalent of commenting out a line)
- dnl # (well, not exactly, but use it for this purpose if you must :-)
- dnl # you generally don't want to override LIBDIR from the compiled in paths
- dnl #define(LIBDIR,/usr/local/lib/mail)dnl # where all support files go
- define(LOCAL_MAILER_DEF, mailers.linux)dnl # mailer for local delivery
- define(POSTMASTERBOUNCE)dnl # postmaster gets bounces
- define(PSEUDODOMAINS, BITNET UUCP)dnl # don't try DNS on these
- dnl #
- dnl #-------------------------------------------------------------
- dnl #
- dnl # names we're known by
- define(PSEUDONYMS, myhostname.subdomain.domain myhostname.UUCP)
- dnl #
- dnl # our primary name
- define(HOSTNAME, myhostname.subdomain.domain)
- dnl #
- dnl # our uucp name
- define(UUCPNAME, myhostname)dnl
- dnl #
- dnl #-------------------------------------------------------------
- dnl #
- define(UUCPNODES, |uuname|sort|uniq)dnl # our uucp neighbors
- define(BANGIMPLIESUUCP)dnl # make certain that uucp
- define(BANGONLYUUCP)dnl # mail is treated correctly
- define(RELAY_HOST, my_uucp_neighbor)dnl # our smart relay host
- define(RELAY_MAILER, UUCP-A)dnl # we reach moria via uucp
- dnl #
- dnl #--------------------------------------------------------------------
- dnl #
- dnl # the various dbm lookup tables
- dnl #
- define(ALIASES, LIBDIR/aliases)dnl # system aliases
- define(DOMAINTABLE, LIBDIR/domaintable)dnl # domainize hosts
- define(PATHTABLE, LIBDIR/pathtable)dnl # paths database
- define(GENERICFROM, LIBDIR/generics)dnl # generic from addresses
- define(MAILERTABLE, LIBDIR/mailertable)dnl # mailers per host or domain
- define(UUCPXTABLE, LIBDIR/uucpxtable)dnl # paths to hosts we feed
- define(UUCPRELAYS, LIBDIR/uucprelays)dnl # short-circuit paths
- dnl #
- dnl #--------------------------------------------------------------------
- dnl #
- dnl # include the 'real' code that makes it all work
- dnl # (provided with the source code)
- dnl #
- include(Sendmail.mc)dnl # REQUIRED ENTRY!!!
- dnl #
- dnl #------------ END OF SAMPLE SENDMAIL.M4 FILE -------
-
-
-
- 6.3.3. Defining a local mailer
-
- Unlike most Unix distributions, Linux did not come with a local mail
- delivery agent by default.
-
- Slackware did! Well at least it is offered by the easy-to-use-but-
- longwinded installation script. It uses procmail.
-
- Now, deliver or procmail is generally installed, with a default
- sendmail setup to handle local mail, so no complexity will be added to
- this already very complex setup. I recommend using the commonly
- available deliver or procmail programs, which can be optional packages
- in a some Linux distributions.
-
- In order to do so, you need to define a LOCAL_MAILER_DEF in the
- sendmail.m4 file that points to a file that looks like:
-
-
- # -- /usr/local/lib/mail/mailers.linux --
- # (local mailers for use on Linux )
- Mlocal, P=/usr/bin/deliver, F=SlsmFDMP, S=10, R=25/10, A=deliver $u
- Mprog, P=/bin/sh, F=lsDFMeuP, S=10, R=10, A=sh -c $u
-
-
-
- There is a also built-in default for deliver in the Sendmail.mc file
- that gets included into the sendmail.cf file. To specify it, you would
- not use the mailers.linux file but would instead define the following
- in your sendmail.m4 file:
-
-
- dnl --- (in sendmail.m4) ---
- define(LOCAL_MAILER_DEF, DELIVER)dnl # mailer for local delivery
-
-
-
- Unfortunately, Sendmail.mc assumes deliver is installed in /bin, which
- is not the case with Slackware1.1.1 (which installs it in /usr/bin).
- In that case you'd need to either fake it with a link or rebuild
- deliver from sources so that it resides in /bin. Please note procmail
- is generally better than deliver, for example for mail filtering.
-
-
- 6.3.4. The sendmail+IDA dbm tables
-
-
- Setting up special behavior for sites or domains is done through a
- number of optional dbm tables rather than editing the sendmail.cf file
- directly.
-
- Refer to the July-1994 issue of Linux Journal (if you can still find
- it:-), to the docs in the sources, or to the sendmail chapter in the
- newest version of the Linux Documentation Project Networking
- Administration Guide which will be available real-soon-now for more
- details.
-
-
- · mailertable - defines special behavior for remote hosts or
- domains.
-
- · uucpxtable - forces UUCP delivery of mail to hosts that are in
- DNS format.
-
- · pathtable - defines UUCP bang-paths to remote hosts or domains.
-
-
- · uucprelays - short-circuits the pathalias path to well-known
- remote hosts.
-
- · genericfrom - converts internal addresses into generic ones
- visible to the outside world.
-
- · xaliases - converts generic addresses to/from valid internal
- ones.
-
- · decnetxtable - converts RFC-822 addresses to DECnet-style
- addresses.
-
-
- 6.3.5. So which entries are really required?
-
- When not using any of the optional dbm tables, sendmail delivers mail
- via the RELAY_HOST and RELAY_MAILER) defined in the sendmail.m4 file
- used to generate sendmail.cf. It is easily possible to override this
- behavior through entries in the domaintable or uucpxtable.
-
- A generic site that is on Internet and speaks Domain Name Service, or
- one that is UUCP-only and forwards all mail via UUCP through a smart
- RELAY_HOST, probably does not need any specific table entries at all.
-
- Virtually all systems should set the DEFAULT_HOST and PSEUDONYMS
- macros, which define the canonical site name and aliases it is known
- by.
-
- If all you have is a relay host and relay mailer, you don't need to
- set these defaults since it works automagically. UUCP hosts will
- probably also need to set UUCPNAME to their official UUCP name.
-
- They will also probably set RELAY_MAILER and RELAY_HOST which enable
- smart-host routing through a mail relay.
-
- The mail transport to be used is defined in RELAY_MAILER and should
- usually be UUCP-A for UUCP sites. If your site is SMTP-only and talks
- `Domain Name Service', you would change the RELAY_MAILER.
-
- If you're a SLIP site, you might want to take the easy way out and
- just forward all outgoing mail to your service provider to do the
- right thing with. To do so, you'd want to define ISOLATED_DOMAINS and
- VALIDATION_DOMAINS to be your domain, you'd also want to define
- RELAY_HOST to be your service provider and RELAY_MAILER to be TCP. Of
- course, you want to ask permission before you set any system up as
- your general purpose relay.
-
-
- 6.4. Sendmail 8.x
-
-
- Sendmail 8.7.x from Berkeley was the latest major revision after
- sendmail5. It had wonderful built-in support for building under Linux
- : just "make linux" and all was set.
-
- You'll probably be best served by grabbing one of the various binary
- distributions off of the usual Linux archive sites rather than
- fighting things like Berkeley dbm yourself.
-
- There's a nice distribution of sendmail 8.6.12 from Jason Haar -
- j.haar at lazerjem.demon.co.uk on sunsite.unc.edu in
- /pub/Linux/system/Mail/delivery/sendmail-8.6.12-bin.tgz that has the
- source documentation and a very nice quickie description of how to run
- sendmail v8 for common configurations.
-
-
- The bottom line with sendmail v8 is that you want to configure the
- bare minimum necessary to get the job done ; the following is an
- example that should get you close at least.
-
-
- 6.4.1. A sample 8.7.x mc file
-
-
- Much like sendmail+IDA, sendmail v8 uses m4 to process a config file
- into a full sendmail.cf that sendmail uses. The following is my
- current mc file for my site (ppp to Internet for outgoing mail, uucp
- for incoming mail).
-
-
- dnl divert(-1)
- #---------------------------------------------------------------------
- #
- # this is the .mc file for a linux host that's set up as follows:
- #
- # - connected to Internet for outbound mail (ppp here)
- # - connected via UUCP for incoming mail
- # - domainized headers
- # - no local mailer (use 'deliver' instead)
- # - no DNS running so don't canonicalize outgoing via DNS
- # - all non-local outbound mail goes to the RELAY_HOST over smtp
- # (we run ppp and let our service provider do the work)
- #
- # vds 3/31/95
- #
- #---------------------------------------------------------------------
- include(`../m4/cf.m4')
- VERSIONID(`linux nodns relays to slip service provider smarthost')dnl
- Cwmyhostname.myprimary.domain myhostname.UUCP localhost
- OSTYPE(linux)
- FEATURE(nodns)dnl
- FEATURE(always_add_domain)dnl
- FEATURE(redirect)
- FEATURE(nocanonify)
- dnl MAILER(local)dnl
- MAILER(smtp)dnl
- MAILER(uucp)dnl
- define(`RELAY_HOST', smtp:my.relay.host.domain)
- define(`SMART_HOST', smtp:my.relay.host.domain)
- define(`UUCP_RELAY', smtp:my.relay.host.domain)
- define(`LOCAL_MAILER_PATH', `/bin/deliver')
- define(`LOCAL_MAILER_ARGS', `deliver $u')
-
-
-
- 6.4.2. Sendmail v8 tidbits
-
-
- There are a few differences I suppose to the 'IDA bigots' among us.
- So far, I've found the following:
-
-
- Instead of 'runq', you type 'sendmail -q' to run the queue!
-
-
-
- 6.5. Local Delivery Agents
-
-
- Unlike most operating systems, Linux did not have mail "built-in": you
- needed a program to deliver the local mail, like "lmail", "procmail"
- or "deliver".
-
- However, every recent distribution includes a local mailer now!
-
- Documentation for how to use either for local delivery is in the
- sendmail5.67b+IDA1.5 binary release (on sunsite) mentioned above.
-
-
- 7. User Agent Administration
-
-
-
- 7.1. Mutt
-
-
- You should have no problem compiling, installing, or running mutt.
- Users of qmail can either get the patch or run it with -f flag to read
- their local mail folder.
-
- If mutt bothers you with an "unknown terminal error" after a
- distribution upgrading, just recompile it.
-
-
- 7.2. Elm
-
-
- Elm compiles, installs and runs flawlessly under Linux. For more
- information, see the elm sources and installation instructions. Elm
- and filter need to be mode 2755 (group mail) with /var/spool/mail mode
- 775 and group mail.
-
- Qmail users can get a patch to use nifty qmail features, or will run
- elm with the -f flag to point to their local mail folder.
-
- One thing you want to be aware of is that if you have Elm compiled to
- be MIME-able, you need metamail installed and in the standard path or
- Elm will not be able to read MIME mail you've received. Metamail is
- available on thumper.bellcore.com and of course via "archie".
-
- If you use a binary distribution, you'll need to create a
- "/usr/local/lib/elm/elm.rc" file to override the compiled-in hostname
- and domain information:
-
-
- · replace "subdomain.domain" with your domain name replace
-
- · "myhostname" with you un-domainized hostname replace
-
-
- #---------- /usr/local/lib/elm/elm.rc ------------------
- #
- # this is the unqualified hostname
- hostname = myhostname
- #
- # this is the local domain
- hostdomain = subdomain.domain
- #
- # this is the fully qualified hostname
- hostfullname = myhostname.subdomain.domain
- #
- #--------------------------------------------------------
-
-
-
- One thing you want to be aware of is that if you have Elm compiled to
- be MIME enabled, you need metamail installed and in your path or Elm
- will not be able to read MIME mail you've received. Metamail is
- available on thumper.bellcore.com and of course via "archie".
-
- In the "too cool to be true" category, there is a distribution of
- Elm-2.4.24 that is "PGP-aware". To try it, grab the file
- ftp://ftp.viewlogic.com/pub/elm-2.4pl24pgp3.tar.gz, which is elm2.4.24
- with PGP hooks added. You configure and build it the same way you do
- normal Elm, which means you probably need to add the patches mentioned
- above. For what it's worth, I run it here and like it a lot. Of
- course, there must be more recent versions available, including elm-
- ME+.
-
- While this item is not Linux-specific, it's perceived (wrongly) to be
- a nagging Elm bug nevertheless. We've heard that Elm sometimes fails
- with a message that it's unable to malloc() some massive number of
- bytes. The identified workaround is to remove the post-processed
- global mail aliases (aliases.dir and aliases.pag).
-
- THIS IS NOT A BUG IN ELM, it's an error in configuration of Elm by
- whomever you got your binary distribution of Elm from.
-
- Elm has an enhanced and non-compatible, format for aliases ; you need
- to ensure that the path Elm uses for aliases is different from the
- path sendmail/smail uses. From the volume of reports of this problem,
- it's apparent that at least one major distribution 'on the street' has
- in the past been misconfigured. (from scot at catzen.gun.de (Scot W.
- Stevenson) )
-
- The current metamail package requires csh for some of its scripts.
- Failure to have csh (or tcsh) will cause most interesting errors...
-
-
- 7.3. Mailx
-
-
- If you don't have a local mailx program, save yourself the pain --
- just go and grab the mailx kit from Slackware 2.1.0 or later, which
- has a nice implementation of mailx5.5. If you're into building from
- sources, mailx v5.5 compiles without patching under Linux if you have
- "pmake" installed.
-
- If anybody is still using it, I strongly recommend removing the old
- "edmail" stuff from SLS1.00 and replacing it with mailx.
-
-
- 8. Handling remote mail
-
-
- This section describes using POP or IMAP to handle remote mail.
-
- Other options include nfs-mounting the spool partition on client
- machines (Danger Will Robinson! Is everyone using the same lock
- method?) or using a mail-to-web gateway (quite popular now).
-
-
- 8.1. History
-
-
- On a workstation network, mail has always been a problem:
-
-
- · Either you use "user@computer.foo.com" with problems when
- "computer" is down, making your network known to the people
- outside, having different addresses for a same person switching to
- another computer, ...
-
- · Or you take a mail hub, "mailhost.foo.com" with rules for
- rewriting, so every user seems to post from the same address, even
- if they are on different computers.
-
- But in that case, how can users read their mail?
-
- Using a rsh with elm? :-)
-
- It would overload our mail hub! One method was forwarding or UUCP,
- smtp, etc. but it's too complicated.
-
- Then came POP/IMAP, both with security problems at the beginning, (now
- fixed using ssh on new versions): a mail program has sometimes to be
- set locally (like qmail, smail or vmail if, for example, you use elm,
- but mozilla will avoid that!) however, getting and sending Email is
- simpler.
-
-
- 8.2. Getting mail
-
-
- Here come POP's main drawbacks:
-
-
- · the password is sent as a clear text on the network,
-
- · you must choose a POP-aware mailer; many do now (like Pine, Emacs,
- Mozilla, Netscape, Mutt, IE, Pegasus, Eudora, Claris...),
-
- · when a user may roam (read mail from different machines) having e-
- mail popped on the computer used yesterday can be a nuisance,
-
- · some POP servers (e.g. qpopper, ipop3d) on high-use servers can
- load the machine significantly. Consider controlling options (such
- as not leaving mail on the server) and/or changing the pop server
- (e.g. cucipop), as well as avoiding running it from inetd.
-
- The password problem can be solved creating a crypted "channel" to
- have POP on it or using APOP or RPOP extensions. The mail reader
- problem can be solved either by changing mail reader (don't
- underestimate the effort required to re-educate users!) or by using a
- POP "mail sucker" with a local mail program.
-
- IMAP can be preferable to POP in various situations like remote (and
- especially roaming) access, while you restrict POP to a LAN where
- snooping of passwords isn't so much of a concern. Mark Aitchison
- reported a solution here is to use hosts.deny and hosts.allow files
- (please see Net-3 HOWTO ; this assumes you are starting pop from
- inet).
-
- The policy of leaving mail on the server or not has implications for
- server disk space and easier backup/security of the mail, as well as
- allowing roaming, so the best solution depends on the type of
- organization. Of course, this will not ensure your mail can't be read,
- but nobody will be able to delete it ; if all your mail is pgp
- encrypted this is a better solution.
-
- Here are some pop programs worth trying:
-
-
- · gwpop (a Good Way to POP) is very protected since it creates a
- crypted "channel" and puts mail directly in the "spool" ; however,
- it depends on Perl.
-
- · popclient, simple to use:
-
- For example if your login is john and your password PrettySecret,
- you will run:
-
-
-
- $ popclient -3 -v mail.acme.net -u john -p "PrettySecret" -k -o JOHN-INET-MAIL
-
-
-
- It is strongly discouraged in case of multi-user machine; other user
- can see your password by, for example with "ps auxw"
-
- · fetchmail, which is actively supported and incredibly simple to
- use: it is configured in ~/.fetchmailrc, so you only need to run
- fetchmail when you want to retrive your mail.
-
- Here's my .fetchmailrc:
-
-
- poll mail.server protocol pop3:
- forcecr
- password PrettySecret;
-
-
-
- Don't forget to "chmod 600 /.fetchmailrc" or fetchmail will ask for
- it.
-
- Please note that the forcecr option is needed to use fetchmail with
- qmail, which strictly respects RFCs.
-
- 8.3. Sending mail
-
- For this, you must use smtp-aware mail software, like qmail, smail,
- vmail or mozilla (this one does everything: mail reader, POP receive,
- smtp send!)
-
- Go to one of the previous sections to install and configure the one
- you like best. Then, when you will reach "Testing", try to send some
- mail to a local account on the mail hub.
-
- 8.4. Reading mail
-
- If your program doesn't do everything itself, you can install elm,
- pgp, mush, pine ... many good programs are freely available for linux
- platforms!
-
-
- 8.5. Testing
-
- To check whether your mail server has pop, try:
-
- $ telnet mailhost 110
-
- If it works, you will get something like "OK Pop server (...)
- starting": type "quit"!
-
- To install a ssh crypted "channel", first test your mail server
- typing:
-
- $ ssh mailhost date
-
- If you get the date, you should be OK. Please note ssh will not ask
- for a password, therefore you must create a ".shosts" file on the mail
- server, containing client's name. To test ssh port redirection (which
- gwpop uses), type:
-
- $ ssh -n -f -L 12314:localhost:110 mailhost sleep 30
-
- then
-
- $ telnet localhost 12314
-
- Then will you hopefully see mail hub's pop banner. If you don't use
- ssh, don't forget to comment out $ssh on gwpop script. To check
- whether procmail is running, try "procmail -v"
-
-
- 8.6. Using
-
-
- Now you can edit gwpop Perl script to check everything is ok, then run
- gwpop:
-
-
-
- $ gwpop -v your-username
- POP password on mailhost: yoursecretpasword
-
-
-
- If gwpop "error messages" are normal, the mail from mail hub will be
- downloaded to your local machine wherever you told gwpop to put it.
- (please test with some mail!).
-
- You can also use gwpop as a daemon:
-
-
-
- $ gwpop -d $HOME/tmp your-username
-
-
-
- gwpop messages are then sent to syslog and gwpop will run endlessly ;
- a "HUP" signal will force gwpop to get your mail.
-
- You can get POP software here used on:
-
- ftp://ftp.unina.it/pub/Unix/pkgs/network/mail/gwpop
- ftp://ftp.informatik.rwth-aachen.de/pub/packages/procmail
- http://www.cs.hut.fi/ssh/
-
- ______________________________________________________________________
-
- Linux Mail-Queue mini-HOWTO
- Leif Erlingsson, leif@lege.com, Jan P Tietze, jpti
- etze@mail.hh.provi.de
- v2.03, 2001-12-17, sendmail 8.8.7
-
- Queue Remote Mail + Deliver Local Mail The Configuration Changes Nec
- cessary to Make Sendmail Deliver Local Mail ***Now*** While Stashing
- Remote Mail in The Queue Until "I Say So".
- ______________________________________________________________________
-
- Table of Contents
-
-
- 1. Introduction
-
- 2. NON dial-on-demand solutions PART
-
- 2.1 Starting sendmail
- 2.2 Configuring sendmail
- 2.2.1 Configuring sendmail.cf directly, for trivial configurations
- 2.2.2 Configuring sendmail.cf using m4 source
- 2.3 Menu support suggestions
-
- 3. Dial-on-demand solutions PART
-
- 3.1 Configuring sendmail.cf
- 3.1.1 Configuring sendmail.cf directly, for trivial configurations
- 3.1.2 Configuring sendmail.cf using the m4 source.
- 3.2 Adding dial delay
- 3.2.1 Configuring sendmail.cf directly
- 3.2.2 Configuring sendmail.cf using m4 source
-
- 4. Delivering e-mail
-
- 4.1 How to have e-mail delivered at special times.
-
- 5. License
-
-
-
- ______________________________________________________________________
-
- 1. Introduction
-
- The document is written by two authors. The NON dial-on-demand
- solutions part (oldest part) is written by Leif Erlingsson
- , and the newer dial-on-demand solutions part is
- written by Jan P Tietze .
-
-
-
- 2. NON dial-on-demand solutions PART
-
- Written by Leif Erlingsson .
-
- The original version of this part contained a lot of unnecessary
- stuff. This is all it takes, really...
-
-
- 2.1. Starting sendmail
-
- Slackware et al: /etc/rc.d/rc.M:
-
-
-
- echo "Starting sendmail daemon (/usr/sbin/sendmail -bd -os) [queue only mode]..."
- /usr/sbin/sendmail -bd -os # NOT "-bd -q 15m", the "standard" flags!
-
-
-
- RedHat et al: /etc/rc.d/init.d/sendmail.init:
-
-
-
- echo -n "Starting sendmail: [queue only mode]"
- daemon sendmail -bd -os # NOT daemon sendmail -bd -q1h
-
-
-
- The -os is not really essential, all it does is this:
-
-
-
- SuperSafe [s] Be super-safe when running things, i.e.,
- always instantiate the queue file, even if
- you are going to attempt immediate delivery.
- Sendmail always instantiates the queue file
- before returning control the client under
- any circumstances. This should really
- always be set.
-
-
-
- This should already be configured in the default sendmail.cf anyway.
-
-
- 2.2. Configuring sendmail
-
- Serious sendmail users use the m4 source for this. I recommend this
- solution if you ever plan on upgrading sendmail and also make anything
- but trivial changes to sendmail.cf.
-
- If you never intend to fix sendmail so envelope return headers et al
- works even though you might be on dynamic dial in IP or something,
- then you may not need to get the m4 source.
-
-
- 2.2.1. Configuring sendmail.cf directly, for trivial configurations
-
- This way of doing things is extremeley version dependent vs.
- sendmail.cf versions. The following solution is *only* valid for
- sendmail-8.8.x.
-
- Edit /etc/sendmail.cf:
-
-
-
- # avoid connecting to "expensive" mailers on initial submission?
- O HoldExpensive=True
-
-
-
- ... later ...
-
- ##### @(#)smtp.m4 8.33 (Berkeley) 7/9/96 #####
-
- Msmtp, P=[IPC], F=mDFMuXe, S=11/31, R=21, E=\r\n, L=990,
- T=DNS/RFC822/SMTP,
- A=IPC $h
- Mesmtp, P=[IPC], F=mDFMuXae, S=11/31, R=21, E=\r\n, L=990,
- T=DNS/RFC822/SMTP,
- A=IPC $h
- Msmtp8, P=[IPC], F=mDFMuX8e, S=11/31, R=21, E=\r\n, L=990,
- T=DNS/RFC822/SMTP,
- A=IPC $h
- Mrelay, P=[IPC], F=mDFMuXa8e, S=11/31, R=61, E=\r\n, L=2040,
- T=DNS/RFC822/SMTP,
- A=IPC $h
-
-
-
- The important flag above is ``e''. Don't fuss if the other flags look
- different in your file. Keep your flags as-is, only add ``e'' to your
- flags according to the above examples, unless it's there already.
- ``e'' marks the mailers as ``expensive''.
-
-
- 2.2.2. Configuring sendmail.cf using m4 source
-
- In the following I will, for simplicity, assume that the sendmail
- version is 8.8.7. If you have a different version, replace 8.8.7 with
- that version number below! Also, the instructions will not work for
- older versions of sendmail. Get the latest sendmail!
-
-
- Download the sendmail source. Try ``http://WWW.Sendmail.ORG'' or
- possibly ``ftp.sendmail.org''.
-
-
- I also recommend that you obtain my patch for allowing envelope sender
- reverse aliasing and other nice stuff to really make you take control
- over your mail environment.
-
- Write to ``Sendmail Patch '', Subject:
- ``sendmail-8.8.7'', if 8.8.7 is your sendmail version.
-
- They are also available from ``http://www.lege.com'', as is the sgml
- source of this mini-HOWTO!
-
- You don't have to get my patches in order to get ``Queue Remote Mail +
- Deliver Local Mail'' to work. My patches solve other things. But I
- just thought this would be a nice place to mention them, as many Linux
- users will find them extremely useful. (They will even give you
- properly working virtual domains, if you like. The virtual domains
- don't have to be ``local''. They will give you ``xaliases'', or in
- other words ``reverse aliasing''.)
-
- Unpack the sendmail source. You may get /usr/src/sendmail-8.8.7/. cd
- /usr/src/sendmail-8.8.7/cf
-
- Now overlay my patch, if you want it, otherwise skip this step: If you
- don't want to use procmail as Local Delivery Agent, save away your
- /usr/src/sendmail-8.8.7/cf/ostype/linux.m4 before doing this... Save
- my patch to ``/tmp/sendmail-8.8.7-cf-cpio-idcmu.gz'', then...
-
-
-
- cd /usr/src/sendmail-8.8.7/cf
- gzip -dc < /tmp/sendmail-8.8.7-cf-cpio-idcmu.gz | cpio -idcmu
-
-
-
- If you didn't want to use procmail, write back the saved copy of
- /usr/src/sendmail-8.8.7/cf/ostype/linux.m4 again.
-
- And regardless of if you applied my patch or not, you must make sure
- these lines or very similar ones are added to
- /usr/src/sendmail-8.8.7/cf/cf/yourhostname.smtp.mc (but if you applied
- my patch you may want to investigate filenames containing the word
- ``elijah'', under /usr/src/sendmail-8.8.7/cf):
-
-
-
- dnl # Defer Delivery to "expensive" mailers until next time the
- dnl # queue is processed using "O HoldExpensive=True" and make
- dnl # sure smtp mailers are "expensive".
- dnl # (See original "sendmail" book Chapter 30: Options,
- dnl # "Oc - Don't connect to expensive mailers", or
- dnl # 2nd Edition "sendmail" book Chapter 34.8.29,
- dnl # "HoldExpensive (c), Queue for expensive mailers".)
- dnl # / Leif Erlingsson
- define(`confCON_EXPENSIVE', `True')
- define(SMTP_MAILER_FLAGS, e)
- MAILER(local)dnl
- MAILER(smtp)dnl
-
-
-
- 2.3. Menu support suggestions
-
- The 1.x versions of this document contained Menu support suggestions
- for /var/X11R6/lib/fvwm/system.fvwmrc. I have dropped those in the
- current version, but they are available on request:
-
-
- Write to ``Menu support suggestions '', Subject:
- ``Menu support suggestions''
-
-
-
- 3. Dial-on-demand solutions PART
-
- Written by Jan P Tietze .
-
- Many Linux users access the Internet through a dialup line, and many
- have decided to implement dial-on-demand facilities on their system.
- That is, whenever an IP packet of some sort has to leave the local
- network or the local host, the link to an Internet Service Provider
- (ISP) will automatically be established. The link will be dropped
- after some period of time that no packet has travelled across.
-
- Although this is very comfortable and cost effective, there is one
- special case in which this is neither comfortable (as the time to
- bring up a "traditional" modem dialup is very noticeable) nor cost
- effective, and this is sending e-mail. E-Mail is commonly sent by
- SMTP, either delivered by your own system or through a SMTP host on
- the Internet that usually resides in your ISP's network.
-
- With dialup lines, every time you send a message the link will have to
- be brought up. This is quite okay if you send only one message, but if
- you happen to create and send multiple messages, bringing up the line
- more than once can be tedious and cost ineffective. Also, if your ISP
- imposes limits as to what times you are allowed to login, this would
- also restrict you to postpone messages at certain times of the day,
- and you would have to manually send them later.
-
- Section 1 of this document will solve the situation, however in
- situations where an external DNS lookup would cause the link up, the
- link will still be established even if e-mail is just being queued.
- The reason is that sendmail wishes to "canonify" host names.
-
- The solution to this problem is twofold: First, we'll have to
- moderately change sendmail.cf. And then we have to define the process
- of actual mail delivery. Personally, I prefer to have cron do the job
- for me and describe the necessary changes below.
-
-
- 3.1. Configuring sendmail.cf
-
- For the reasons stated in [1.2], I recommend modifying the m4 sources
- instead of editing sendmail.cf directly. It will actually save you a
- lot of hassle and make configuration changes more verbose.
-
- First, perform all the changes described in the first part of this
- document. Then go through the dial-on-demand specific stuff.
-
-
- 3.1.1. Configuring sendmail.cf directly, for trivial configurations
-
- Configuring directly is highly impractical and anything but verbose,
- but obviously, this is your decision.
-
- Close to very bottom of your sendmail.cf should be a line that reads:
-
-
-
- R$* < @ $* $~P > $* $: $1 < @ $[ $2 $3 $] > $4
-
-
-
- Precede that line with a "#" so that it reads
-
-
-
- #R$* < @ $* $~P > $* $: $1 < @ $[ $2 $3 $] > $4
-
-
-
- 3.1.2. Configuring sendmail.cf using the m4 source.
-
- Add the following line to
- /usr/src/sendmail-8.8.7/cf/cf/yourhostname.smtp.mc:
-
-
-
- FEATURE(nocanonify)dnl
-
-
-
- Your final sendmail.cf can then be built by issuing the following
- commands. Remember to always back up your old /etc/sendmail.cf before
- installing the new one:
- cp /etc/sendmail.cf /etc/sendmail.cf.bak
- cd /usr/src/sendmail-8.8.7/cf/cf
- m4 yourhostname.smtp.mc > /etc/sendmail.cf
-
-
-
- 3.2. Adding dial delay
-
- It is oftentimes useful, especially when using modem lines, to have a
- dial delay installed. This means that if sendmail tries to initiate a
- connection in an attempt to send an e-mail (and this causes the line
- to go up) but the link actually takes more time to get established
- than what sendmail thinks should be a reasonable timeout, sendmail
- will simply wait some seconds and then retry.
-
-
- 3.2.1. Configuring sendmail.cf directly
-
- Somewhere in your sendmail.cf could be a line that would read:
-
-
-
- #O DialDelay=10s
-
-
-
- (or very similar). Delete the ``#''. If there's no ``#'' at the
- beginning of the line, things should be considered okay (it just means
- this had already been enabled before).
-
- If there is no such line in your sendmail.cf, add one (it is a wise
- thing to do to add this in the "options" part of the file):
-
-
-
- O DialDelay=10s
-
-
-
- Now change the ``10s'' part to the number of seconds you deem
- suitable.
-
-
- 3.2.2. Configuring sendmail.cf using m4 source
-
- Add the following line to
- /usr/src/sendmail-8.8.7/cf/cf/yourhostname.smtp.mc:
-
-
-
- define(`confDIAL_DELAY',`10s')
-
-
-
- Now change the ``10s'' part to the number of seconds you deem
- suitable.
-
- Your final sendmail.cf can then be built by issuing the following
- commands. Remember to always back up your old /etc/sendmail.cf before
- installing the new one:
-
- cp /etc/sendmail.cf /etc/sendmail.cf.bak
- cd /usr/src/sendmail-8.8.7/cf/cf
- m4 yourhostname.smtp.mc > /etc/sendmail.cf
-
-
-
- 4. Delivering e-mail
-
- E-Mail delivery can be invoked by issuing the command "sendmail -q".
- For those who are interested in what sendmail actually does, "sendmail
- -q -v" will give a more verbose version of the delivery process.
-
- It is very convenient to automate the process of e-mail delivery. A
- tool commonly used for this process is cron.
-
-
- 4.1. How to have e-mail delivered at special times.
-
- Edit your crontab:
-
-
-
- crontab -e
-
-
-
- Add lines of the form:
-
-
-
- 05 18-23,0-7 * * Mon,Tue,Wed,Thu,Fri /usr/sbin/sendmail -q
- 05 * * * Sat,Sun /usr/sbin/sendmail -q
-
-
-
- Please refer to the crontab man page (available through "man 5 \
- crontab") for further information. I think the format is pretty
- obvious. The example crontab entries shown above send e-mail (if, and
- only if, e-mail is available from the queue) 5 minutes after an hour
- on weekdays, starting at 6:05 pm, and stopping at 7:05 am. On
- weekends, e-mail is delivered 5 minutes after an hour, starting at
- 12:05 pm on Saturday, and stopping 11:05 pm on Sunday.
-
- As a dial-on-demand user, it is sometimes desirable to have your
- system collect your e-mail via the POP3 protocol at certain times of
- the day. You could therefore add an entry similar to the following to
- your crontab:
-
-
-
- 0 21 * * * popclient -3 -u -p -o /var/spool/mail/
-
-
-
-
- Of course, this should all go on a single line.
-
- Then, save the file and leave the editor. The crontab should now be
- installed.
- 5. License
-
- This document is distributed under the terms of the GNU Free
- Documentation License. You should have received a copy along with it.
- If not, it is available from http://www.fsf.org/licenses/fdl.html.
-
-The Linux Mail User HOWTO
-
-Eric Steven Raymond
-
-[http://www.catb.org/~esr/] Thyrsus Enterprises
-
-
-
-
-
-Copyright © 2000 Eric S. Raymond
-
-
-This document is an introduction to the world of electronic mail (email)
-under Linux. It focuses on user-level issues and typical configurations for
-Linux home and small-business machines connected to the net via an ISP.
-
-You need to read this if you plan to communicate locally or to remote sites
-via electronic mail. You probably do not need to read this document if don't
-exchange electronic mail with other users on your system or with other sites.
-
-For information on configuring and administering mail, see the Mail
-Administrator HOWTO.
-
------------------------------------------------------------------------------
-Table of Contents
-1. Introduction
- 1.1. New versions of this document
- 1.2. Hardware requirements for email programs
- 1.3. Software sources for email programs
-
-
-2. Mail User Agents
- 2.1. Setting your mail editor
- 2.2. mutt
- 2.3. elm
- 2.4. pine
- 2.5. Netscape
- 2.6. Emacs rmail/smail and vm.
- 2.7. BSD mail
- 2.8. Other user agents
-
-
-3. Advanced topics
- 3.1. Aliases
- 3.2. Forwarding
- 3.3. Auto-replying
- 3.4. Mailing lists
- 3.5. Mail filters
- 3.6. Coping with spam
-
-
-4. Other sources of information
- 4.1. USENET
- 4.2. Books
- 4.3. Periodic USENET Postings
- 4.4. Where not to look for help
-
-
-5. Administrivia
- 5.1. Feedback
- 5.2. Copyright Information
- 5.3. Standard Disclaimer
- 5.4. Acknowledgements
-
-
-
-1. Introduction
-
-The intent of this document is to explain how email works, and answer some of
-the questions that appear to meet the definition of `frequently asked
-questions' about e-mail software under Linux.
-
-Modern Linux distributions give you a usable, preconfigured setup for
-electronic mail out of the box, usually featuring a late version of
-sendmail-v8. This HOWTO will assume that you have such a setup and a working
-Internet connection.
-
-(For information on how to set up a PPP or SLIP link to an ISP, see the ISP
-Hookup HOWTO.)
-
-Accordingly, unlike Vince Skahan's 1.x versions, this HOWTO focuses on user
-issues and architecture; most technical hair about UUCP, IDA sendmail and
-other formerly important topics has been dropped.
-
------------------------------------------------------------------------------
-
-1.3. Software sources for email programs
-
-The software you will need for email support is probably preinstalled in your
-Linux distribution. You will find updates on the Metalab Linux Archive,
-especially in the mail subdirectory.
------------------------------------------------------------------------------
-
-2. Mail User Agents
-
-This section contains information related to user agents, which means the
-software the user sees and uses. This software relies on the transport agents
-described in the Mail Administrator's HOWTO (which also include user-agent
-configuration and troubleshooting tips for administrators).
------------------------------------------------------------------------------
-
-2.1. Setting your mail editor
-
-Mail user agents call out to some editor to assist composition of mail. Which
-editor is the default varies. Most of them respect a convention going back to
-Unix's early days; the contents of the environment variable VISUAL, if it
-exists, is taken as the name of your preferred editor. If VISUAL is not set,
-the variable EDITOR is checked.
-
-Popular values for EDITOR include vi and emacs. But if you are, like me, the
-sort who always has a GNU Emacs running, the most useful way to set EDITOR is
-to the value emacsclient. Use this with the following lines in your ~/.emacs
-file:
-(autoload 'server-edit "server" nil t)
-(server-edit)
-
-The emacsclient program, when it runs, tries to establish communication with
-an Emacs instance you already have running and hand the mail message
-temporary file to that Emacs to be edited. The effect of this will be that
-when your mailer calls out for an editor, a mail composition window pops open
-inside your Emacs.
-
-When you are ready to hand the file back to the mailer for sending, type C-x
-#. The mail buffer will leave your display and the emacsclient instance your
-mailer called will return, handing control back to the mailer.
-
-It is possible to have more than one emacsclient instance open at once
-without confusing Emacs. However, calling up another Emacs while an
-emacsclient session is running can confuse emacsclient enough that it won't
-be able to find either instance afterwards. If this happens, shut down all
-your Emacs instances and restart just one.
-
-If you're running XEmacs rather than GNU Emacs, these directions change
-slightly. In this case you waant to set EDITOR to gnuclient. In recent
-versions, your init file will live at ~/.xemacs/init.el rather than ~/.emacs.
------------------------------------------------------------------------------
-
-2.2. mutt
-
-This is what I use and recommend. It is descended from elm and has similar
-commands by default, but is much more powerful and configurable. It can be a
-POP3 or IMAP client, and includes excellent support for MIME and PGP. There
-is a [http://www.mutt.org] Mutt home page on the web.
-
-Mutt respects the EDITOR/VISUAL convention.
------------------------------------------------------------------------------
-
-2.3. elm
-
-Elm was the first modern, screen-oriented Unix mailer, but has been stagnant
-for years now and is being displaced by Mutt. Some versions of elm have POP3
-support built in. For more information, see the elm sources and installation
-instructions in the Metalab mail user agents directory. Here are a few points
-that occasionally trip people up:
-
-No, stock elm is not PGP-aware. There are PGP support patches, but Mutt's PGP
-support is superior. If you want to use PGP, I recommend Mutt.
-
-Elm respects the EDITOR/VISUAL convention.
------------------------------------------------------------------------------
-
-2.4. pine
-
-Pine is a user agent designed for novices; it includes news-reading
-capability and built-in support for the IMAP remote-mail protocol. A lot of
-people swear by it for new users. I find its impoverished command set,
-limited configurability and native editor hard to take. It has excellent
-built-in IMAP support, however. If you want to check it out, the distribution
-is available at [http://www.washington.edu/pine] http://www.washington.edu/
-pine.
-
-Pine respects the EDITOR/VISUAL convention.
------------------------------------------------------------------------------
-
-2.5. Netscape
-
-The Netscape browser has POP3 and IMAP remote-mail capability built into it,
-so it can be used as a mail user agent. I don't recommend this; it doesn't
-specialize in being an MUA, and therefore does not offer many of the services
-that real MUAs do (such as aliases and PGP handling). It does, however,
-support LDAP and SSL.
-
-Netscape supplies its own mini-editor, the same one used throughout the
-browser (e.g. for text fields in forms).
------------------------------------------------------------------------------
-
-2.6. Emacs rmail/smail and vm.
-
-Emacs has a mode called smail that can send mail, and another called rmail
-that can read mail. The smail mode can be quite useful, as you get to compose
-mail inside a full Emacs environment (but see also the discussion of
-emacsclient elsewhere in this document).
-
-The rmail mode, on the other hand, is not recommended. Every time you run it,
-it converts your inbox to BABYL format; ordinary mail tools will choke on
-that. (If this happens to you, do M-x unrmail from the Emacs command line.)
-
-There is a mailreader for emacs called `vm' that writes and reads standard V7
-mailboxes. It is not distributed with GNU Emacs, but you can find its home
-page at [http://www.wonderworks.com/vm/] http://www.wonderworks.com/vm/.
-
-The most popular mailreader for emacs is probably GNUS, distributed with GNU
-Emacs. It is a client for USENET news as well as mail.
-
-Emacs smail/rmail/vm do not respect the EDITOR/VISUAL convention. Instead,
-you use the Emacs they're embedded in.
------------------------------------------------------------------------------
-
-2.7. BSD mail
-
-If you simply type `mail' to the shell on a Linux or any other modern Unix,
-you will invoke some variant of the BSD Mail program. It has a line-oriented
-interface originally designed for use on TTYs. It is, at this point, only of
-historical interest.
-
-BSD Mail invented the EDITOR/VISUAL convention.
------------------------------------------------------------------------------
-
-2.8. Other user agents
-
-The following also are known to run under Linux. Consult `archie' to find
-them...
-
-mush
- mail user's shell, very powerful for filtering andbatch processing
-
-mh
- mail handler, yet another mail user agent
-
-
-I don't know enough about mh or mush to describe them in detail. They both
-have rather complex interfaces and are designed for sophisticated mail users.
------------------------------------------------------------------------------
-
-3. Advanced topics
-
-3.1. Aliases
-
-An `alias' is a way to set up a pseudo-address that simply directs mail to
-another (single) address. There are two kinds of aliases: MUA aliases and MTA
-aliases.
-
-An MUA alias is one you set up in your MUA as a kind of personal shorthand.
-Other people will not be able to see or use this alias. For example, you
-could write:
-alias esr Eric S. Raymond
-
-in your mutt configuration file. This would tell mutt that when it sees `esr'
-in an address line, it should behave as through you had typed
-`esr@thyrsus.com', Or you can type `mutt esr' and the expanded address will
-be automatically filled in on the `to' line.
-
-An MTA alias is one your MTA expands; it will be usable by everyone, both on
-your machine and remotely. To create MTA aliases you must modify a system
-file, usually but not always /etc/aliases or /etc/mail/aliases (the location
-depends on your MTA). It may be instructive for you to look at the the
-aliases on your system; it should contain a number of standard aliases such
-as `postmaster'.
-
-Your MTA may also allow the target of an alias to be a filename, which will
-be treated as a mailbox the mail is to be appended to (this is useful for
-archiving mail). It may also allow the target of an alias to be a program, in
-which case mail to that alias will be passed to an instance of the program on
-its standard input.
------------------------------------------------------------------------------
-
-3.2. Forwarding
-
-MTA aliases usually require administrator privileges to set up. But it is
-desirable for mail users to be able to set up forwarding of their own mail
-without administrator intervention.
-
-To support this, most MTAs follow sendmail's lead and look for a file called
-.forward in your home directory. The contents of this file is interpreted
-like the target of an alias which should receive all your mail. The most
-common use for this facility is to redirect your mail to an account on
-another machine.
------------------------------------------------------------------------------
-
-3.3. Auto-replying
-
-Another common use for the .forward facility is to pass your mail to a
-`vacation' program. A vacation program reads incoming mail and automatically
-generates a canned reply to it; they are so called because the most common
-form of canned reply is to inform the sender that you are on vacation and
-will not be reachable until a given date.
-
-There is no one standard vacation program that is in universal use. There are
-two good reasons for this: one, that such a program is very easy to write as
-a shellscript or filter rule (see below); and two, that vacation programs
-interact badly with mailing lists.
-
-You should temporarily unsubscribe from all mailing lists you are on before
-setting up auto-answering; otherwise, all members of the mailing lists mail
-find they are being flooded with canned messages by your vacation program.
-This is considered very rude behavior and will guarantee you quite a frosty
-reception on your return.
------------------------------------------------------------------------------
-
-3.4. Mailing lists
-
-A mailing list is a pseudo-address that sends mail to more than one user.
-
-In its simplest form, mailing list is just an MTA alias with more than one
-recipient. Some small mailing lists are maintained this way. Sendmail assists
-by supporting a syntax in /etc/aliases that includes the contents of a given
-mailing list file in the target side of an alias. It looks like this:
-admin-list: ":include:/usr/home/admin/admin-list"
-
-with the advantage that the admin-list file can live in unprivileged-user
-space somewhere (root is only needed to set up the original inclusion). Some
-other MTAs have similar features.
-
-These simple lists are commonly called `mail reflectors'. There are a couple
-of problems with mail reflectors. One is that bounce messages from failed
-attempts to broadcast goes to all users. Another is that all subscriptions
-and unsubscriptions have to be done manually by the mailing list
-administrator.
-
-A kind of software called a mailing list manager has evolved to address these
-problems and other related ones. Its most important function is to permit
-mailing list users to subscribe and unscubscribe without going through the
-list maintainer.
-
-A mailing-list manager keeps its own user-list information and hooks up to
-the MTA through a program alias in /etc/aliases. For example, if the
-admin-list above were going through the mailing list manager called SmartList
-on a sendmail system, a portion of /etc/aliases might look like this:
-admin-list: "|/usr/home/smartlist/bin/flist admin-list"
-admin-list-request: "|/usr/home/smartlist/bin/flist admin-list-request"
-
-Note that this is a pair of aliases. It is conventional for real mailing
-lists to have a request address to be used for user subscription and
-unsubscription requests. It is considered rude and ignorant to send
-subscription/unsubscription requests to the main address of such a list --
-don't do it.
-
-The robot sitting behind the request address may offer other features besides
-just subscription/unsubscription. It may respond to help requests, allow you
-to query who is on the list, or give you automated access to list archives.
-It may also allow list administrators to restrict posting to known members,
-set the list to auto-subscribe nonmembers when they first post, or set
-various security policy options. Mailing-list managers differ primarily in
-the design and range of these secondary features.
-
-Unfortunately, the format for sending commands to mailing-list request robots
-is not standard. Some expect commands in the subject line, some ignore the
-subject line and expect commands in the message body. You need to pay
-attention to the response mail you get when you first subscribe; it's a good
-idea to save such mail to a subscriptions mailbox for later reference.
-
-The most important mailing-list managers to know about are majordomo,
-listserv, listproc, and smartlist; majordomo is the most popular by a
-considerable margin. Recently, [http://www.gnu.org/software/mailman/
-mailman.html] mailman, a list manager with a rather nice Web-based signon/
-signoff/administration interface, has become very popular and may be in the
-pricess of obsolescing the older programs. There is a rather comprehensive
-[http://www.catalog.com/vivian/mailing-list-software.html] list of such
-packages on the Web.
-
-For more about mailing list managers, consult the resources at the
-List-Managers Mailing List, including the FAQ (note: this list is not
-appropriate for how-to questions).
------------------------------------------------------------------------------
-
-3.5. Mail filters
-
-A mail filter is a program that sits between your local delivery agent and
-you, automatically dispatching or rejecting mail before you see it.
-
-Mail filters have a number of uses. The most important are spam filtering,
-dispatching to multiple mailboxes by topic or sender, and auto-answering
-mail.
-
-Typically, you set up mail filtering by putting a program alias for the
-filter program in your .forward file, and writing a file of filtering rules.
-The format and location of the filter rules file varies between filter
-programs.
-
-There are good feature summaries of the three major mail filters (procmail,
-mailagent, and deliver) in part 3 of Chris Lewis's Email Software Survey. The
-most popular of these is (despite its rather nasty rule syntax) procmail,
-which is universally present on Linux systems (and, indeed, is generally used
-as the system's local delivery agent).
------------------------------------------------------------------------------
-
-3.6. Coping with spam
-
-Spam is sometimes known as `UCE' (Unsolicited Commercial Email) or `UBE'
-(Unsolicited Bulk Email). As these names imply, it is an obnoxious form of
-advertising that stuffs your mailbox with form letters. (The term `spam'
-comes from a Monty Python's Flying Circus skit in which a choir of Vikings
-endlessly repeats the chant "Spam spam spam spam...").
-
-Most spam seems to consist of solicitations for pyramid schemes, ads for
-pornography, or (annoyingly) attempts to sell spam-sending programs. A few
-individual spams (like MAKE MONEY FAST or the Craig Shergold postcard hoax)
-have been so persistent as to become legendary. Spam tends to be both verbose
-and illiterate. It's a waste of time and a huge waste of network bandwidth.
-
-The spam epidemic seems to have peaked in mid-1997 and been slowly in decline
-since, but it can still be a serious annoyance. If you're being deluged with
-spam, get educated. Browse the [http://spam.abuse.net/] Fight Spam on the
-Internet! page. The Death To Spam! page is particularly effective on methods
-for stopping or backtracking spam.
------------------------------------------------------------------------------
-
-4. Other sources of information
-
-4.1. USENET
-
-There are a number of Usenet groups devoted to electronic-mail technical
-issues:
-
-[news:comp.mail.elm] comp.mail.elm
- the ELM mail system.
-
-[news:comp.mail.mh] comp.mail.mh
- The Rand Message Handling system.
-
-[news:comp.mail.mime] comp.mail.mime
- Multipurpose Internet Mail Extensions.
-
-[news:comp.mail.misc] comp.mail.misc
- General discussions about computer mail.
-
-[news:comp.mail.multi-media] comp.mail.multi-media
- Multimedia Mail.
-
-[news:comp.mail.mush] comp.mail.mush
- The Mail User's Shell (MUSH).
-
-[news:comp.mail.sendmail] comp.mail.sendmail
- the BSD sendmail agent.
-
-[news:comp.mail.smail] comp.mail.smail
- the smail mail agent.
-
-[news:comp.mail.uucp] comp.mail.uucp
- Mail in the uucp environment.
-
-
------------------------------------------------------------------------------
-4.2. Books
-
-The following is a non-inclusive set of books that will help...
-
-Sendmail
- from O'Reilly and Associates is the definitive reference on sendmail-v8
- and sendmail+IDA. It's a ``must have'' for anybody hoping to make sense
- out of sendmail without bleeding in the process.
-
-The Internet Complete Reference
- from Osborne is a fine reference book that explains the various services
- available on Internet and is a great source for information on news,
- mail, and various other Internet resources.
-
-The Linux Networking Administrators' Guide
- from Olaf Kirch of the LDP is available on the net and is also published
- by (at least) O'Reilly and SSC. It makes a fine one-stop shopping guide
- to learn about everything you ever imagined you'd need to know about Unix
- networking.
-
-
------------------------------------------------------------------------------
-4.3. Periodic USENET Postings
-
-Also worth mentioning is Chris Lewis' periodic posting on unix e-mail
-software, which is available on [ftp://rtfm.mit.edu/pub/usenet/
-comp.mail.misc] ftp://rtfm.mit.edu/pub/usenet/comp.mail.misc as the files
-named ``UNIX_Email_Software_Survey_*''. An HTMLized version is at [http://
-www.faqs.org/faqs/mail/setup/unix/] http://www.faqs.org/faqs/mail/setup/unix
-/. At time writing in 1999 this posting has not been seriously updated since
-1996, however.
------------------------------------------------------------------------------
-
-4.4. Where not to look for help
-
-There is no longer anything special about configuring and running mail under
-Linux, relative to other Unixes. Accordingly, you almost certainly do not
-want to be posting generic mail-related questions to the comp.os.linux.*
-newsgroups.
-
-Unless your posting is truly Linux-specific (ie, ``please tell me what
-routers are already compiled into the SLS1.03 version of smail3.1.28'') you
-should be asking your questions in one of the newsgroups or mailing lists
-referenced above.
-
-Let me repeat that....
-
-There is virtually no reason to post anything mail-related in the
-comp.os.linux hierarchy any more. There are existing newsgroups in the
-comp.mail.* hierarchy to handle all your questions.
-
-If you post to comp.os.linux.* for non-Linux-specific questions, you are
-looking in the wrong place for help. The electronic mail experts hang out in
-the places indicated above and generally not in the Linux groups.
-
-Posting to the Linux hierarchy for non-linux-specific questions wastes your
-time and everybody else's...and it frequently delays you from getting the
-answer to your question.
+* Linux Mail-Queue mini-HOWTO
+
+* The Linux Mail User HOWTO
diff --git a/LDP/guide/docbook/Linux-Networking/FTP.xml b/LDP/guide/docbook/Linux-Networking/FTP.xml
index 9640da3c..90fc6694 100644
--- a/LDP/guide/docbook/Linux-Networking/FTP.xml
+++ b/LDP/guide/docbook/Linux-Networking/FTP.xml
@@ -29,487 +29,6 @@ servers. There are many FTP clients available. Some are graphical, and
some are text-based.
-
-
-3. Beginner's guide to using ftp
-A quick guide to using ftp.
-
-The standard ftp program is the original ftp client. It comes standard with most Linux
-distributions. It first appeared in 4.2BSD, which was developed by the University of
-California, Berkeley.
-
-
-
-3.1 Running the ftp program
-It's easy to use ftp. Let's say you want to connect to the anonymous ftp site
-metalab.unc.edu, to download the latest Linux kernel source.
-At the command line, type:
-
-
-
-
-$ ftp metalab.unc.edu
-
-
-
-
-The ftp program will attempt to connect to metalab.unc.edu. Another way to do this is
-to run ftp from the command line with no parameters, and use the open command, with
-the site name as an argument:
-
-
-
-
-$ ftp
-ftp> open metalab.unc.edu
-
-
-
-
-3.2 Logging into an FTP server
-When you connect to an FTP site, it will ask you for a login (pressing enter will
-log in as your local user name, in this case, foo: We log in as anonymous or ftp,
-to get to the public archive.
-
-
-
-
-220 helios.oit.unc.edu FTP server (Version wu-2.6.0(2) Wed Nov 17 14:44:12
-EST 1999) ready.
-Name (metalab.unc.edu:foo):
-
-
-
-
-Now, we enter a complete e-mail address as the password (this is what most public
-FTP sites request).
-
-
-
-
-331 Guest login ok, send your complete e-mail address as password.
-Password:
-
-
-
-
-After a successful login, the following information is given to us:
-
-
-
-
-Remote system type is UNIX.
-Using binary mode to transfer files.
-ftp>
-
-
-
-
-3.3 File transfer types
-After you log in to an ftp site, ftp will print out the file transfer type. In
-our case, it is binary. Binary mode transfers the files, bit by bit, as they
-are on the FTP server. Ascii mode, however, will download the text directly.
-You can type ascii or binary to switch between the types.
-
-
-
-You want to download the kernel source, so you leave the file transfer type at
-binary. The binary type is also what you would use for any non-text files --
-such as graphic images, zip/gzip archives, executable programs, etc. If in
-doubt, use binary mode.
-
-
-
-3.4 Navigating and listing directories
-You do an ls to see a list of the files. The ls command on ftp servers is
-executed on the remote server, so the command line options that you can use
-with it vary from server to server. The most common options are generally
-available, check the manpage for ls for details.
-
-
-
-
-ftp> ls
-200 PORT command successful.
-150 Opening ASCII mode data connection for /bin/ls.
-total 33590
--r--r--r-- 1 root other 34348506 Dec 03 03:53 IAFA-LISTINGS
-lrwxrwxrwx 1 root other 7 Jul 15 1997 README -> WELCOME
--rw-r--r-- 1 root other 890 Nov 15 13:11 WELCOME
-dr-xr-xr-x 2 root other 512 Jul 15 1997 bin
-dr-xr-xr-x 2 root other 512 Jul 15 1997 dev
-dr-xr-xr-x 2 root other 512 Jul 18 1997 etc
-drwxrwxrwx 11 ftp 20 4608 Nov 28 16:00 incoming
-lrwxrwxrwx 1 root other 13 Jun 04 1998 ls-lR -> IAFA-LISTINGS
-dr-xr-xr-x 17 root root 512 Jun 08 11:43 pub
-dr-xr-xr-x 3 root other 512 Jul 15 1997 unc
-dr-xr-xr-x 5 root other 512 Jul 15 1997 usr
-226 Transfer complete.
-
-
-
-
-If the ls command lists so many files that they scroll off the top of the
-screen, you can use Shift-PageUp to scroll up. This works in Linux console
-mode as well as in xterm or rxvt.
-
-On public FTP archives, the downloadable resources are usually held in the
-/pub directory. In this example, you already know that the kernel sources
-are in the directory /pub/Linux/kernel, so you type the following to get
-into that directory:
-
-
-
-ftp> cd pub/Linux/kernel
-250-README for kernel
-250-
-250-What you'll find here: kernel sources and patches
-250-
-250-
-250 CWD command successful.
-
-
-
-
-The messages you see, which begin with "250", are information messages sent
-by the server. In this case, the ftp server is configured to automatically
-send you the README file when you cd into the directory.
-
-
-
-3.5 Downloading and uploading files
-Now, after doing another ls, you see that you want to cd into the v2.2
-directory. You do yet another ls, and find the file you want to download.
-It is linux-2.2.13.tar.gz. So you type this:
-
-
-
-
-ftp> get linux-2.2.13.tar.gz
-local: linux-2.2.13.tar.gz remote: linux-2.2.13.tar.gz
-200 PORT command successful.
-150 Opening BINARY mode data connection for linux-2.2.13.tar.gz (15079540
-bytes).
-
-
-
-
-The ftp program has started saving the remote file linux-2.2.13.tar.gz as
-the local file linux-2.2.13.tar.gz.
-
-
-
-If you wanted to save it as the local file foo.tar.gz, you could have
-specified it like this:
-
-
-
-
-ftp> get linux-2.2.13.tar.gz foo.tar.gz
-local: foo.tar.gz remote: linux-2.2.13.tar.gz
-200 PORT command successful.
-150 Opening BINARY mode data connection for linux-2.2.13.tar.gz (15079540
-bytes).
-
-
-
-
-If you want to download more than one file at a time, you'll have to use
-the mget (multiple get) command. You can use mget together with a
-space-delimited list of filenames you want to download, or you can use
-wildcards with the mget command. For example:
-
-
-
-
-ftp> mget linux*
-
-
-
-
-Would get all files starting with the string "linux". Normally, mget will
-prompt you for each file before it downloads it. You can toggle this by
-using the prompt command.
-
-
-
-Now let's say you've written a piece of software, and you want to upload
-it to MetaLab to be included in their Linux software archive. First,
-you'd change to the /incoming directory (most public FTP servers have a
-directory, usually called incoming or uploads, where files can be
-uploaded), then you'd use the put command:
-
-
-
-
-ftp> cd /incoming
-ftp> put foo.tar.gz
-local: foo.tar.gz remote: foo.tar.gz
-200 PORT command successful.
-150 Opening BINARY mode data connection for foo.tar.gz.
-226 Transfer complete.
-10257 bytes sent in 0.00316 secs (3.2e+03 Kbytes/sec)
-
-
-
-
-The put command works the same way as the get command, so you can use
-mput to upload multiple files at the same time. You can also upload a
-local file with a different filename on the server by specifying the
-remote filename and/or pathname as an argument.
-
-
-
-What if the file foo.tar.gz is not in your current local directory
-when you try to upload it? You can switch local directories by using
-the lcd (local change directory) command:
-
-
-
-
-ftp> lcd /home/foo/
-Local directory now /home/foo
-
-
-
-
-3.6 Running shell commands
-The ftp client supports using the bang (!) to run local commands. For
-example, to get a listing of files in your current local directory, do this:
-
-
-
-
-ftp> !ls
-
-
-
-
-The way this works is that ftp calls the shell (specified in the $SHELL
-environment variable), and it is the shell which runs ls. Thus, you can
-run any command-line which works with your shell simply by prepending "!"
-to it (the default shell in most Linux distributions is bash, the Bourne
-Again SHell). Please note that !cd does not work as you would expect,
-this is why the lcd command exists.
-
-
-
-3.7 Hash marks and tick
-Wouldn't it be nice if you could watch the progress while you're downloading
-a file with ftp? You can use the hash command to print out hash marks as you
-download a file:
-
-
-
-
-ftp> hash
-Hash mark printing on (1024 bytes/hash mark).
-
-
-
-
-As you can tell, ftp will print a hash mark for every 1024 bytes of data
-you download. There is also a tick option.
-
-
-
-
-ftp> tick
-Tick counter printing on (10240 bytes/tick increment).
-
-
-
-
-This will print something to this effect as you download a file:
-
-
-
-
-Bytes transferred: 11680
-
-
-
-
-3.8 Other ftp commands
-There are many other ftp commands. If you have the permissions to do so
-(which you should, if you are connected to your own private shell account),
-you can make a directory on the remote server using the mkdir command.
-You can remove a file on the remote server using the delete command, or
-rmdir to remove a directory. You can also change file permissions using the
-chmod command.
-
-
-
-For more elaborate information on using ftp, please see the online help in
-the ftp program (accessible by typing help with no arguments for a list of
-commands, or help for specific help on a command). You can
-also read the Unix man page for ftp by typing man ftp at your command prompt.
-
-
-
-4. Console FTP clients
-The original ftp program was the original ftp client, and it is a good
-investment to learn it. It's the only ftp client that you can be certain
-is available on most systems (even Win32 comes with the ftp command, albeit
-an archaic, braindead version of it).
-
-
-
-There are many other console-mode (text-only) ftp clients available. The
-listing here is by no means comprehensive, but includes the most popular
-ones. Search at FreshMeat to find more.
-
-
-
-4.1 NcFTP
-NcFTP is the all-time favorite ftp client of many Unix users. It comes
-bundled with most Linux distributions, and offers many advanced features such
-as tab completion and bookmarks. Version 2 of NcFTP had a curses based
-full-screen mode. This was done away with in Version 3 (now in beta).
-It's not 100% compatible with the commands that standard ftp uses. For example,
-get and put in NcFTP act like mget and mput do in standard ftp. So if you want
-to save a remote file as a different local filename, you'd have to
-do get -z remotename localname. Thankfully, NcFTP has a nice online help system
-to assist you in learning the commands.
-You can get the latest version of NcFTP at http://www.ncftp.com.
-
-
-
-4.2 lukemftp
-A port of the NetBSD FTP client to other systems, lukemftp derives its name
-from the author of most of the enhanced features, which include:
-command-line editing, command-line fetches of FTP and HTTP URLs (including
-via proxies), context-sensitive word completion, dynamic progress bar,
-IPv6 support, modification time preservation, paging of local and remote
-files, passive mode support (with fallback to active mode), SOCKS support,
-TIS FWTK gate-ftp server support, and transfer rate throttling.
-lukemftp is espically good for users who don't want to change to anything
-drastically different from the standard ftp client, but want more advanced features.
-You can get the latest version of lukemftp at
-ftp://ftp.netbsd.org/pub/NetBSD/misc/lukemftp/.
-
-
-
-4.3 lftp
-lftp is a sophisticated command line based FTP client. Like bash, it has job
-control. It uses the GNU readline library for input, so you have command line
-completion and editing. lftp also has bookmarks, mirroring support, and can
-transfer several files in parellel.
-You can get the latest version of lftp at http://ftp.yars.free.net/projects/lftp/.
-Debian packages are available at ftp://ftp.freshmeat.net/pub/debs/lftp/.
-
-
-
-4.4 cftp
-Comfortable FTP (cftp) is a full screen mode client. What it lacks in features,
-it makes up for in ease of use. You browse through the directories using the
-arrow keys and enter.
-You should be able to get the latest version of cftp at
-http://ftp.giga.or.at/pub/nih/cftp/.
-
-
-
-4.5 yafc
-Yafc is a very nice ftp client, with features including directory cache,
-remote filename completion, aliases, colorized ls, recursive get/put/ls/rm,
-nohup mode transfers, tagging (queueing), multiple connections, proxy support
-and more. It has support for Kerberos4 authentication.
-You can get the latest version of yafc from
-http://www.stacken.kth.se/~mhe/yafc/.
-Debian packages are available at
-http://members.home.com/decklin/experimental/.
-Redhat packages are available at
-http://lz.freeservers.com/linux/yafc.html.
-
-
-
-5. X Window FTP clients
-There are several graphical FTP clients designed to run on the X Window
-system. These clients offer ease of use for users who are used to
-graphical environments, and sometimes offer versatile options that would
-be hard to implement in a text-based ftp client.
-
-
-
-5.1 gFTP
-gFTP is an FTP client for X Windows written using Gtk. The interface has
-some similarities to the popular WS_FTP software commonly used on a certain
-unstable operating system.
-gFTP features simultaneous downloads, resuming of interrupted file transfers,
-file transfer queues, downloading of entire directories, ftp proxy support,
-remote directory caching, passive and non-passive file transfers, drag-n-drop
-support, a very nice connection manager and more.
-If you are running Red Hat Linux and have the GNOME desktop installed, then
-you probably already have gFTP. If not, you can download gFTP from its
-homepage at http://gftp.seul.org/.
-
-
-
-5.2 WXftp
-WXftp is an FTP client for the X Window System designed to be used mainly
-on Linux workstations. It is written using the WXWindows toolkit, so it
-can be compiled to use either Motif or GTK+
-It includes an intuitive user interface (much like WS_FTP), a session
-manager, on-line help, a progress bar, and more
-Check out WXftp's homepage at http://www.wxftp.seul.org.
-
-
-
-5.3 LLNL XDIR and XFTP
-LLNL XFTP was one of the first graphical FTP clients for Linux. It supports
-FXP (file transfer between two remote hosts), and has a Motif based interface.
-More information is available at http://www.llnl.gov/ia/xdir_xftp/.
-
-
-
-5.4 guiftp
-Guiftp is a simple ftp client written with the GTK+ toolkit. It's good if
-you don't need many features and want a simple, clean look.
-Guiftp's homepage is at http://www.altern.org/ldufresne/guiftp/.
-
-
-
-6. FTP Servers
-6.1 How an FTP Server works
-A traditional FTP server is executed from inetd (the internet superserver
-daemon). The standard FTP port is port 21. When a user tries to log in, the
-FTP server uses a standard system call to check the user name and password
-against the entries in the system password file, or the NIS tables if you
-are using NIS. If the login is correct, the user is given access to the system.
-Anonymous FTP works differently. The user logs in with either the anonymous
-or the ftp username (this can be defined in the config file). He is then
-given access to a directory tree that has been chroot()'ed. This ensures
-that the user can not gain access to directory trees he is not authorized
-for. The chrooted directory tree usually contains a mock filesystem,
-with bin/, etc/, and lib/ directories. The files for download are usually
-put in the pub/ directory.
-The reason for a mock filesystem in an anonymous FTP tree is that the FTP
-daemon runs external commands for ls requests. You can also place additional
-programs in the bin directory, and a user can run them with the SITE command
-in his ftp client. For example, Red Hat's FTP includes the RPM command
-(for users to query RPM packages on the site).
-Some FTP servers work differently. For example, some will allow user accounts
-to be set up independant of the system-wide password file (FTP-only accounts).
-Some servers (ProFTPD and NcFTPd for instance) have built-in ls commands and
-do not need a special directory tree within the chroot structure. Other ftp
-servers stray altogether from the standard ftp concept. FTP4ALL, for example,
-does not use system passwords at all. It uses it's own user and group file,
-and has features such as upload/download ratio and customizable server messages.
-
-
-
-6.2 Help with FTP Servers
-WU-FTPD
-WU-FTPD is the ftp daemon included with many Linux distributions, including
-Red Hat and Caldera. You can learn more about WU-FTPD at http://www.wu-ftpd.org.
-The WU-FTPD FAQ can be found on the web at http://www.cetis.hvu.nl/~koos/wu-ftpd-faq.html.
-
-
-
-ProFTPD
-ProFTPD is a powerful FTP server that includes Apache-style configuration,
-extensive support for virtual hosts, and internal ls.
-A complete command reference and downloads can be found at http://www.proftpd.org
-
+* FTP HOWTO
diff --git a/LDP/guide/docbook/Linux-Networking/Firewalling-and-Masquerading.xml b/LDP/guide/docbook/Linux-Networking/Firewalling-and-Masquerading.xml
index d532f77e..ef7d89cc 100644
--- a/LDP/guide/docbook/Linux-Networking/Firewalling-and-Masquerading.xml
+++ b/LDP/guide/docbook/Linux-Networking/Firewalling-and-Masquerading.xml
@@ -231,13800 +231,12 @@
Masquerading Made Simple HOWTO
-John Tapsell
-
-
-
-Thomas Spellman
-
-
-
-Matthias Grimm
-
-
-Revision History
-Revision 0.09 2004-07-21 Revised by: ts
-Revision 0.08 2002-07-11 Revised by: jpt
-Revision 0.07 2002-02-27 Revised by: jpt
-Revision 0.06 2001-09-08 Revised by: jpt
-Revision 0.05 2001-09-07 Revised by: jpt
-Revision 0.04 2001-09-01 Revised by: jpt
-Revision 0.03 2001-07-06 Revised by: jpt
-
-
-All of the authors are available on #debian on irc.opensource.net
-
-John Tapsell (JohnFlux) is the official maintainer.
-
-Email me (John Tapsell) for any query, flame, feedback, a date, etc.
-
-Shamelessly stealing from David Ranch's work - .
-
-This is NOT a replacement for the IP-Masquerading HOWTO - it is to complement
-it, and the two should be read side by side. I do not include things in here
-that are covered by the the other HOWTO, nor do I explain what it all means,
-or what it is all about. See [http://ipmasq.cjb.net] http://ipmasq.cjb.net
-and the standard Masq-HOWTO for a much better guides.
-
-This document describes how to enable the Linux IP Masquerade feature on a
-given Linux host. IP Masq is a form of Network Address Translation or NAT
-that allows internally networked computers that do not have one or more
-registered Internet IP addresses to have the ability to communicate to the
-Internet via your Linux boxes single Internet IP address.
-
-This is all under the GNU Free Documentation License
-
-http://www.gnu.org/copyleft/fdl.html
-
------------------------------------------------------------------------------
-Table of Contents
-1. Introduction
-2. Summary: (I like doing summaries first)
-3. Bitmore indepth version
-4. Post-install Instructions
-5. FAQ's - Frequently Asked Compla^H^H^H^H^H^H Questions
-
-1. Introduction
-
-This is intentionally short and to the point.
-
-If you have a network, that you want to attach to the outside:
-
-[network]
------------------------------------------------------------------------------
-
-2. Summary: (I like doing summaries first)
-
-Assuming external internet card is eth0, and external IP is 123.12.23.43 and
-the internal network card is eth1, then:
-+---------------------------------------------------------------------------+
-|$> modprobe ipt_MASQUERADE # If this fails, try continuing anyway |
-|$> iptables -F; iptables -t nat -F; iptables -t mangle -F |
-|$> iptables -t nat -A POSTROUTING -o eth0 -j SNAT --to 123.12.23.43 |
-|$> echo 1 > /proc/sys/net/ipv4/ip_forward |
-+---------------------------------------------------------------------------+
-
-Or for a dial-up connection:
-+---------------------------------------------------------------------------+
-|$> modprobe ipt_MASQUERADE # If this fails, try continuing anyway |
-|$> iptables -F; iptables -t nat -F; iptables -t mangle -F |
-|$> iptables -t nat -A POSTROUTING -o ppp0 -j MASQUERADE |
-|$> echo 1 > /proc/sys/net/ipv4/ip_forward |
-+---------------------------------------------------------------------------+
-
-Then to secure it:
-+---------------------------------------------------------------------------+
-|$> iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT |
-|$> iptables -A INPUT -m state --state NEW -i ! eth0 -j ACCEPT |
-|$> iptables -P INPUT DROP #only if the first two are succesful |
-|$> iptables -A FORWARD -i eth0 -o eth0 -j REJECT |
-+---------------------------------------------------------------------------+
-
-Or for a dial-up connection (with eth0 as the internal network card):
-+---------------------------------------------------------------------------+
-|$> iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT |
-|$> iptables -A INPUT -m state --state NEW -i ! ppp0 -j ACCEPT |
-|$> iptables -P INPUT DROP #only if the first two are succesful |
-|$> iptables -A FORWARD -i ppp0 -o ppp0 -j REJECT |
-+---------------------------------------------------------------------------+
-
-And thats it! To view the rules do "iptables -t nat -L"
------------------------------------------------------------------------------
-
-3. Bitmore indepth version
-
-Compiling the kernel: (Use a 2.4.x kernel or greater)
-
-You need the following support in the kernel:
-
- * Under Networking Options
-
- + Network packet filtering (CONFIG_NETFILTER)
-
-
- * Under Networking Options->Netfilter Configuration
-
- + Connection tracking (CONFIG_IP_NF_CONNTRACK)
-
- + FTP Protocol support (CONFIG_IP_NF_FTP)
-
- + IP tables support (CONFIG_IP_NF_IPTABLES)
-
- + Connection state match support (CONFIG_IP_NF_MATCH_STATE)
-
- + Packet filtering (CONFIG_IP_NF_FILTER)
-
- o REJECT target support (CONFIG_IP_NF_TARGET_REJECT)
-
-
- + Full NAT (CONFIG_IP_NF_NAT)
-
- o MASQUERADE target support (CONFIG_IP_NF_TARGET_MASQUERADE)
-
- o REDIRECT target support (CONFIG_IP_NF_TARGET_REDIRECT)
-
-
- + Packet mangling (CONFIG_IP_NF_MANGLE)
-
- + LOG target support (CONFIG_IP_NF_TARGET_LOG)
-
-
-
-First, if the iptable and masq modules are not compiled into the kernel and
-not installed, but do exist as modules, we need to install them. If you
-insmod ipt_MASQUERADE it will load ip_tables, ip_conntrack and iptable_nat.
-+---------------------------------------------------------------------------+
-|$> modprobe ipt_MASQERADE |
-+---------------------------------------------------------------------------+
-
-Now either your Intranet is large, or you're just trying to get two or three
-machines to work on the internet - it doesn't make much difference either
-way.
-
-Okay, I'm assuming that you have no other rules, so do:
-+---------------------------------------------------------------------------+
-|$> iptables -F; iptables -t nat -F; iptables -t mangle -F |
-+---------------------------------------------------------------------------+
-
-If you get an error saying can't find iptables, go find it and install it. If
-it says no such table 'nat', recompile the kernel with nat support. If it
-says no such table as 'mangle', don't worry about it, it's not necessary for
-MASQ'ing. If it says iptables is incompatible with your kernel, go get > 2.4
-and compile that with iptables support.
-
-Then if you have a static ip do (e.g. network card not using DHCP):
-+---------------------------------------------------------------------------+
-|$> iptables -t nat -A POSTROUTING -o eth0 -j SNAT --to 123.12.23.43 |
-+---------------------------------------------------------------------------+
-
-or for dynamic (e.g. a modem - you have to call a number first):
-+---------------------------------------------------------------------------+
-|$> iptables -t nat -A POSTROUTING -o ppp0 -j MASQUERADE |
-+---------------------------------------------------------------------------+
-
-Then finally to tell the kernel yes, you really do want to start forwarding
-packets: (This only needs to be done once per reboot - but dosen't hurt to do
-it lots)
-+---------------------------------------------------------------------------+
-|$> echo 1 > /proc/sys/net/ipv4/ip_forward |
-+---------------------------------------------------------------------------+
-
-Once you have checked this all works (See under Post-install) only allow
-masquerading from the internal network - you don't want to allow people on
-the internet to use it after all :)
-
-First, allow any existing connections, or anything related (e.g. ftp server
-connecting back to you)
-+---------------------------------------------------------------------------+
-|$> iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT |
-+---------------------------------------------------------------------------+
-
-If this gives an error, then you most likely don't have state tracking in the
-kernel - go recompile. Then allow new connections only from our intranet
-(local/internal network). Replace the ppp0 with eth0 or whatever your
-external device is. (The ! means anything but)
-+---------------------------------------------------------------------------+
-|$> iptables -A INPUT -m state --state NEW -i ! ppp0 -j ACCEPT |
-+---------------------------------------------------------------------------+
-
-And now deny everything else:
-+---------------------------------------------------------------------------+
-|$> iptables -P INPUT DROP #only if the first two are succesful |
-+---------------------------------------------------------------------------+
-
-If either of the first two rules failed, then this last rule with prevent the
-masquerading from working at all. To undo this rule do "iptables -P INPUT
-ACCEPT".
------------------------------------------------------------------------------
-
-4. Post-install Instructions
-
-And it should all work now. Don't forget to:
-
- * Setup all the clients on the internal network to point to the Linux
- internal IP address as their gateway. (In windows right-click network
- neighbourhood->properties->gateway then change it to the Linux gateway
- internal ip.)
-
- * Setup all the clients to use your ISP's HTTP proxy if they have one, use
- a transparent proxy (WARNING - I've heard reports of transparent proxying
- to be very slow on very big networks), or run squid on your new linux
- gateway. (This is optional, but preferrable for large networks)
-
- * Be sure to specify a DNS when setting up your clients. Otherwise you will
- get errors on the clients saying 'cannot resolve address' etc. If DNS
- used to work (URL address worked) but doesn't after you setup
- Masquerading, this is because your ISP's/network's DHCP server can no
- longer tell you what the DNS address is.
-
- [Offtopic] I wonder if you could simply send out a dhcp broadcast that
- just forwards on the dns server (and http_proxy while you're at it)
- without having to setup a dhcp server (or even if you do). Can someone
- mail me about this? :)
-
- Thanks to Richard Atcheson for pointing this out.
-
- * Now you should start securing it! First turn off forwarding in general: "
- iptables -P FORWARD DROP", and then learn how to use iptables and /etc/
- hosts.allow and /etc/hosts.deny to secure your system. WARNING - Don't
- try this mentioned iptables rule until you have the masquerading working.
- You have to explicitely allow every packet through that you want if you
- are going to set the last rule to be DENY. (Undo with "iptables -P
- FORWARD ACCEPT")
-
- * Allow through any services you do want the internet to see.
-
- For an example, to allow access to your web server do:
- +---------------------------------------------------------------+
- |$> iptables -A INPUT --protocol tcp --dport 80 -j ACCEPT |
- |$> iptables -A INPUT --protocol tcp --dport 443 -j ACCEPT |
- +---------------------------------------------------------------+
-
- To allow ident (For connecting to irc etc) do
- +---------------------------------------------------------------+
- |$> iptables -A INPUT --protocol tcp --dport 113 -j ACCEPT |
- +---------------------------------------------------------------+
-
-
-To test it:
-
- * Try connecting from a client to the web using an IP. Google's IP is
- 216.239.33.100 (well that's one of them) and you should be able to get a
- reply from that. e.g. "ping 216.239.33.100" "lynx 216.239.33.100".
-
- * Try a full out connection by name. e.g. "ping google.com" "lynx
- google.com" or from Internet Explorer / netscape.
-
-
-Where eth0 is the external Internet card, and 123.12.23.43 is the external ip
-of that machine.
------------------------------------------------------------------------------
-
-5. FAQ's - Frequently Asked Compla^H^H^H^H^H^H Questions
-
- * How do I list the rules I've got so far?
-
- - Try
- +---------------------------------------------------------------+
- |$> iptables -L |
- |$> iptables -t nat -L |
- +---------------------------------------------------------------+
-
- * It won't resolve IP's! I'm typing 'www.microsoft.com' in and it says it
- can't find it!
-
- - Make sure you add the dns server ip to all the clients.
-
- * It don't work! It doesn't like iptables / NAT / SNAT / MASQ
-
- - Go get the latest kernel, and compile with iptables and full NAT
- support.
-
- * It don't work! The masquerading doesn't work at all! Die scum!
-
- - Try echo 1 > /proc/sys/net/ipv4/ip_forward
-
- * It don't work! I can't use the network at all and I hate you!
-
- - Try
- +---------------------------------------------------------------+
- |$> iptables -F |
- |$> iptables -t nat -F |
- |$> iptables -t mangle -F |
- +---------------------------------------------------------------+
-
- (all rules went bye-bye) then rerun the other iptables rules.
-
- - Try iptables -P FORWARD ACCEPT
-
- * It still don't work!
-
- - Hmm, does "dmesg | tail" give any errors? or "cat /var/log/messages |
- tail" ? Like I care tho...
-
- * I don't get, it just ain't working!
-
- - I dunno.. but you should be able to:
- +---------------------------------------------------------------+
- | 1) From the gateway machine, ping the outside |
- | 2) From the gateway ping your internal machines |
- | 3) From the internal machines ping the gateway |
- +---------------------------------------------------------------+
-
- And this is before you play with masq'ing
-
- * Where do I put this stuff?
-
- - In the /etc/network/interfaces file, or firewall.rc. If you put it in
- the interfaces file, then put it as a pre-up to the external interface,
- and have "iptables -t nat -F" as the post-down.
-
- * How do I get it to only bring the ppp up on demand?
-
- - Assuming your ISP gateway IP is say 23.43.12.43 for arguments sake,
- then append a line like this:
-
- :23.43.12.43
-
- to /etc/ppp/peers/provider at the end. (this is for dynamic IP - static
- IP would be my.external.ip.number:23.43.12.43 )
-
- Then at the end of that file add on a newline:
-
- demand
-
- Pppd will remain in the background to redial the connection on demand if
- it's dropped until you do an "ifdown ppp0" or a "poff", unless you add a
- "nopersist" option, in which case pppd will exit after the connection is
- up. You can also add on a new line "idle 600" to disconnect after 10 mins
- of idleness.
-
-
- * The connection keeps dropping!
-
- - First, do you have demand dialing? Is it just doing what it is supposed
- to? Check /etc/ppp/peers/provider, and make sure your dial up works fine
- before attempting masq'ing.
-
- - Secondly, if not, then perhaps, like me, something is going weird, and
- you need to fall back to Linux 2.4.3 and see if that works instead..
- dunno why.
-
- * I hate doing this myself! I want a pre-made script and GUI and stuff.
-
- - Sure: [http://shorewall.sourceforge.net/] http://
- shorewall.sourceforge.net/
-
- Eat your heart out!
-
- * Do I count Cable modems as static or dynamic IP's?
-
- - Good question.. might as well make it dynamic.
-
- * Do I count DHCP network cards as static or dynamic IP's?
-
- - They are dynamic.
-
- * How do I handle incomming services?
-
- - Try forwarding or redirecting the IP ports - again make sure you
- firewall this if needed.
-
- * From the clients, I can ping the linux gateway's external IP address, but
- can't access the internet.
-
- - Okay, try doing "rmmod iptable_filter" - more info on this as I get it.
-
- - Make sure your not running routed or gated - to check run "ps aux |
- grep -e routed -e gated".
-
- - Look at [http://ipmasq.cjb.net] http://ipmasq.cjb.net
-
- * How can I view the connections establish? Something like netstat..
-
- - Try cat /proc/net/ip_conntrack
-
- * I need more squid info and routing and stuff!
-
- - Try the Advanced Routing HOWTO http://www.linuxdoc.org/HOWTO/
- Adv-Routing-HOWTO.html
-
- * This howto is crap! How do I yell at the guys who wrote this?
-
- - Go to #debian on irc.opensource.net and find and locate JohnFlux. -
- Mail me (JohnFlux) at tapselj0@cs.man.ac.uk
-
- * This howto is crap! How can I see better versions?
-
- - Try [http://ipmasq.cjb.net] http://ipmasq.cjb.net
-
- - Consult the LDP Masq-HOWTO.
-
- * What else are you working on?
-
- Currently I'm writing a guide on linux on
- anti-missile-missiles-made-simple. There's no good guides on protecting
- your system from nuclear attacks for newbies. People seem to think its
- rocket science or something..
-
- Linux IPCHAINS-HOWTO
- Rusty Russell
- v1.0.8, Tue Jul 4 14:20:53 EST 2000
-
- This document aims to describe how to obtain, install and configure
- the enhanced IP firewalling chains software for Linux, and some ideas
- on how you might use them.
- ______________________________________________________________________
-
- Table of Contents
-
-
-
- 1. Introduction
-
- 1.1 What?
- 1.2 Why?
- 1.3 How?
- 1.4 Where?
-
- 2. Packet Filtering Basics
-
- 2.1 What?
- 2.2 Why?
- 2.3 How?
- 2.3.1 A Kernel With Packet Filtering
- 2.3.2 ipchains
- 2.3.3 Making Rules Permanent
-
- 3. I'm confused! Routing, masquerading, portforwarding, ipautofw...
-
- 3.1 Rusty's Three-Line Guide To Masquerading
- 3.2 Gratuitous Promotion: WatchGuard Rules
- 3.3 Common Firewall-like Setups
- 3.3.1 Private Network: Traditional Proxies
- 3.3.2 Private Network: Transparent Proxies
- 3.3.3 Private Network: Masquerading
- 3.3.4 Public Network
- 3.3.5 Limited Internal Services
- 3.4 More Information on Masquerading
-
- 4. IP Firewalling Chains
-
- 4.1 How Packets Traverse The Filters
- 4.1.1 Using ipchains
- 4.1.2 What You'll See When Your Computer Starts Up
- 4.1.3 Operations on a Single Rule
- 4.1.4 Filtering Specifications
- 4.1.4.1 Specifying Source and Destination IP Addresses
- 4.1.4.2 Specifying Inversion
- 4.1.4.3 Specifying Protocol
- 4.1.4.3.1 Specifying UDP and TCP Ports
- 4.1.4.3.2 Specifying ICMP Type and Code
- 4.1.4.4 Specifying an Interface
- 4.1.4.5 Specifying TCP SYN Packets Only
- 4.1.4.6 Handling Fragments
- 4.1.5 Filtering Side Effects
- 4.1.5.1 Specifying a Target
- 4.1.5.2 Logging Packets
- 4.1.5.3 Manipulating the Type Of Service
- 4.1.5.4 Marking a Packet
- 4.1.5.5 Operations on an Entire Chain
- 4.1.5.6 Creating a New Chain
- 4.1.5.7 Deleting a Chain
- 4.1.5.8 Flushing a Chain
- 4.1.5.9 Listing a Chain
- 4.1.5.10 Resetting (Zeroing) Counters
- 4.1.5.11 Setting Policy
- 4.1.6 Operations on Masquerading
- 4.1.7 Checking a Packet
- 4.1.8 Multiple Rules at Once and Watching What Happens
- 4.2 Useful Examples
- 4.2.1 Using ipchains-save
- 4.2.2 Using ipchains-restore
-
- 5. Miscellaneous.
-
- 5.1 How to Organize Your Firewall Rules
- 5.2 What Not To Filter Out
- 5.2.1 ICMP packets
- 5.2.2 TCP Connections to DNS (nameservers)
- 5.2.3 FTP Nightmares
- 5.3 Filtering out Ping of Death
- 5.4 Filtering out Teardrop and Bonk
- 5.5 Filtering out Fragment Bombs
- 5.6 Changing Firewall Rules
- 5.7 How Do I Set Up IP Spoof Protection?
- 5.8 Advanced Projects
- 5.8.1 SPF: Stateful Packet Filtering
- 5.8.2 Michael Hasenstein's ftp-data hack
- 5.9 Future Enhancements
-
- 6. Common Problems
-
- 6.1 ipchains -L Freezes!
- 6.2 Inverse doesn't work!
- 6.3 Masquerading/Forwarding Doesn't Work!
- 6.4 -j REDIR doesn't work!
- 6.5 Wildcard Interfaces Don't Work!
- 6.6 TOS Doesn't Work!
- 6.7 ipautofw and ipportfw Don't Work!
- 6.8 xosview is Broken!
- 6.9 Segmentation Fault With `-j REDIRECT'!
- 6.10 I Can't Set Masquerading Timeouts!
- 6.11 I Want to Firewall IPX!
-
- 7. A Serious Example.
-
- 7.1 The Arrangement
- 7.2 Goals
- 7.3 Before Packet Filtering
- 7.4 Packet Filtering for Through Packets
- 7.4.1 Set Up Jumps From forward Chain
- 7.4.2 Define the icmp-acc Chain
- 7.4.3 Good (Internal) to DMZ (Servers)
- 7.4.4 Bad (external) to DMZ (servers).
- 7.4.5 Good (internal) to Bad (external).
- 7.4.6 DMZ to Good (internal).
- 7.4.7 DMZ to bad (external).
- 7.4.8 Bad (external) to Good (internal).
- 7.4.9 Packet Filtering for the Linux Box Itself
- 7.4.9.1 Bad (external) interface.
- 7.4.9.2 DMZ interface.
- 7.4.9.3 Good (internal) interface.
- 7.5 Finally
-
- 8. Appendix: Differences between ipchains and ipfwadm.
-
- 8.1 Quick-Reference table.
- 8.2 Examples of translated ipfwadm commands
-
- 9. Appendix: Using the ipfwadm-wrapper script.
-
- 10. Appendix: Thanks.
-
- 10.1 Translations
-
-
- ______________________________________________________________________
-
- 1. Introduction
-
- This is the Linux IPCHAINS-HOWTO; see ``Where?'' for the master site,
- which contains the latest copy. You should read the Linux NET-3-HOWTO
- as well. The IP-Masquerading HOWTO, the PPP-HOWTO, the Ethernet-HOWTO
- and the Firewall HOWTO might make interesting reading. (Then again,
- so might the alt.fan.bigfoot FAQ).
-
-
- If packet filtering is passe to you, read Section ``Why?'', Section
- ``How?'', and scan through the titles in Section ``IP Firewalling
- Chains''.
-
-
- If you are converting from ipfwadm, read Section ``Introduction'',
- Section ``How?'', and Appendices in section ``Differences between
- ipchains and ipfwadm'' and section ``Using the `ipfwadm-wrapper'
- script''.
-
-
- 1.1. What?
-
- Linux ipchains is a rewrite of the Linux IPv4 firewalling code (which
- was mainly stolen from BSD) and a rewrite of ipfwadm, which was a
- rewrite of BSD's ipfw, I believe. It is required to administer the IP
- packet filters in Linux kernel versions 2.1.102 and above.
-
-
- 1.2. Why?
-
- The older Linux firewalling code doesn't deal with fragments, has
- 32-bit counters (on Intel at least), doesn't allow specification of
- protocols other than TCP, UDP or ICMP, can't make large changes
- atomically, can't specify inverse rules, has some quirks, and can be
- tough to manage (making it prone to user error).
-
-
- 1.3. How?
-
- Currently the code is in the mainstream kernel from 2.1.102. For the
- 2.0 kernel series, you will need to download a kernel patch from the
- web page. If your 2.0 kernel is more recent than the supplied patch,
- the older patch should be OK; this part of the 2.0 kernels is fairly
- stable (eg. the 2.0.34 kernel patch works just fine on the 2.0.35
- kernel). Since the 2.0 patch is incompatible with the ipportfw and
- ipautofw patches, I don't recommend applying it unless you really need
- some functionality that ipchains offers.
-
-
- 1.4. Where?
-
- The official page is in three places: Thanks to Penguin Computing
- Thanks to the SAMBA Team
- Thanks to Jim Pick
-
-
-
- There is a mailing list for bug reports, discussion, development and
- usage. Join the mailing list by sending a message containing the word
- ``subscribe ipchains-list'' to subscribe at east.balius.com. To mail
- to everyone on the list use ipchains-list at east.balius.com.
-
-
- 2. Packet Filtering Basics
-
- 2.1. What?
-
- All traffic through a network is sent in the form of packets. For
- example, downloading this package (say it's 50k long) might cause you
- to receive 36 or so packets of 1460 bytes each, (to pull numbers at
- random).
- The start of each packet says where it's going, where it came from,
- the type of the packet, and other administrative details. This start
- of the packet is called the header. The rest of the packet,
- containing the actual data being transmitted, is usually called the
- body.
-
-
- Some protocols, such TCP, which is used for web traffic, mail, and
- remote logins, use the concept of a `connection' -- before any packets
- with actual data are sent, various setup packets (with special
- headers) are exchanged saying `I want to connect', `OK' and `Thanks'.
- Then normal packets are exchanged.
-
-
- A packet filter is a piece of software which looks at the header of
- packets as they pass through, and decides the fate of the entire
- packet. It might decide to deny the packet (ie. discard the packet as
- if it had never received it), accept the packet (ie. let the packet go
- through), or reject the packet (like deny, but tell the source of the
- packet that it has done so).
-
-
- Under Linux, packet filtering is built into the kernel, and there are
- a few trickier things we can do with packets, but the general
- principle of looking at the headers and deciding the fate of the
- packet is still there.
-
-
- 2.2. Why?
-
- Control. Security. Watchfulness.
-
-
-
- Control:
- when you are using a Linux box to connect your internal network
- to another network (say, the Internet) you have an opportunity
- to allow certain types of traffic, and disallow others. For
- example, the header of a packet contains the destination address
- of the packet, so you can prevent packets going to a certain
- part of the outside network. As another example, I use Netscape
- to access the Dilbert archives. There are advertisements from
- doubleclick.net on the page, and Netscape wastes my time by
- cheerfully downloading them. Telling the packet filter not to
- allow any packets to or from the addresses owned by
- doubleclick.net solves that problem (there are better ways of
- doing this though).
-
-
- Security:
- when your Linux box is the only thing between the chaos of the
- Internet and your nice, orderly network, it's nice to know you
- can restrict what comes tromping in your door. For example, you
- might allow anything to go out from your network, but you might
- be worried about the well-known `Ping of Death' coming in from
- malicious outsiders. As another example, you might not want
- outsiders telnetting to your Linux box, even though all your
- accounts have passwords; maybe you want (like most people) to be
- an observer on the Internet, and not a server (willing or
- otherwise) -- simply don't let anyone connect in, by having the
- packet filter reject incoming packets used to set up
- connections.
-
-
- Watchfulness:
- sometimes a badly configured machine on the local network will
- decide to spew packets to the outside world. It's nice to tell
- the packet filter to let you know if anything abnormal occurs;
- maybe you can do something about it, or maybe you're just
- curious by nature.
-
-
- 2.3. How?
-
- 2.3.1. A Kernel With Packet Filtering
-
- You need a kernel which has the new IP firewall chains in it. You can
- tell if the kernel you are running right now has this installed by
- looking for the file `/proc/net/ip_fwchains'. If it exists, you're
- in.
-
-
- If not, you need to make a kernel that has IP firewall chains. First,
- download the source to the kernel you want. If you have a kernel
- numbered 2.1.102 or higher, you won't need to patch it (it's in the
- mainstream kernel now). Otherwise, apply the patch from the web page
- listed above, and set the configuration as detailed below. If you
- don't know how to do this, don't panic -- read the Kernel-HOWTO.
-
-
-
- The configuration options you will need to set for the 2.0-series
- kernel are:
-
-
- ______________________________________________________________________
- CONFIG_EXPERIMENTAL=y
- CONFIG_FIREWALL=y
- CONFIG_IP_FIREWALL=y
- CONFIG_IP_FIREWALL_CHAINS=y
- ______________________________________________________________________
-
-
-
- For the 2.1 or 2.2 series kernels:
-
- ______________________________________________________________________
- CONFIG_FIREWALL=y
- CONFIG_IP_FIREWALL=y
- ______________________________________________________________________
-
-
-
- The tool ipchains talks to the kernel and tells it what packets to
- filter. Unless you are a programmer, or overly curious, this is how
- you will control the packet filtering.
-
-
- 2.3.2. ipchains
-
- The ipchains tool inserts and deletes rules from the kernel's packet
- filtering section. This means that whatever you set up, it will be
- lost upon reboot; see ``Making Rules Permanent'' for how to make sure
- they are restored the next time Linux is booted.
-
-
- ipchains replaces ipfwadm, which was used for the old IP Firewall
- code. There is a set of useful scripts available from the ipchains
- ftp site:
-
-
- http://netfilter.filewatcher.org/ipchains/ipchains-
- scripts-1.1.2.tar.gz
-
-
-
- This contains a shell script called ipfwadm-wrapper which allows you
- to do packet filtering as it was done before. You probably shouldn't
- use this script unless you want a quick way of upgrading a system
- which uses ipfwadm (it's slower, and doesn't check arguments, etc).
- In that case, you don't need this HOWTO much either.
-
- See Appendix ``Differences between ipchains and ipfwadm'' and Appendix
- ``Using the `ipfwadm-wrapper' script'' for more details on ipfwadm
- issues.
-
-
- 2.3.3. Making Rules Permanent
-
- Your current firewall setup is stored in the kernel, and thus will be
- lost on reboot. I recommend using the `ipchains-save' and `ipchains-
- restore' scripts to make your rules permanent. To do this, set up
- your rules, then run (as root):
-
-
-
- # ipchains-save > /etc/ipchains.rules
- #
-
-
-
- Create a script like the following:
-
-
-
- #! /bin/sh
- # Script to control packet filtering.
-
- # If no rules, do nothing.
- [ -f /etc/ipchains.rules ] || exit 0
-
- case "$1" in
- start)
- echo -n "Turning on packet filtering:"
- /sbin/ipchains-restore < /etc/ipchains.rules || exit 1
- echo 1 > /proc/sys/net/ipv4/ip_forward
- echo "."
- ;;
- stop)
- echo -n "Turning off packet filtering:"
- echo 0 > /proc/sys/net/ipv4/ip_forward
- /sbin/ipchains -F
- /sbin/ipchains -X
- /sbin/ipchains -P input ACCEPT
- /sbin/ipchains -P output ACCEPT
- /sbin/ipchains -P forward ACCEPT
- echo "."
- ;;
- *)
- echo "Usage: /etc/init.d/packetfilter {start|stop}"
- exit 1
- ;;
- esac
-
- exit 0
-
-
-
- Make sure this is run early in the bootup procedure. In my case
- (Debian 2.1), I make a symbolic link called `S39packetfilter' in the
- `/etc/rcS.d' directory (this will be run before S40network).
-
-
- 3. I'm confused! Routing, masquerading, portforwarding, ipautofw...
-
- This HOWTO is about packet filtering. This means deciding whether a
- packet should be allowed to pass or not. However, Linux being the
- hacker's playground that it is, you probably want to do more than
- that.
-
-
- One problem is that the same tool (``ipchains'') is used to control
- both masquerading and transparent proxying, although these are
- notionally separate from packet filtering (the current Linux
- implementation blurs these together unnaturally, leaving the
- impression that they are closely related).
-
-
- Masquerading and proxying are covered by separate HOWTOs, and the auto
- forwarding and port forwarding features are controlled by separate
- tools, but since so many people keep asking me about it, I'll include
- a set of common scenarios and indicate when each one should be
- applied. The security merits of each setup will not be discussed
- here.
-
-
- 3.1. Rusty's Three-Line Guide To Masquerading
-
- This assumes that your external interface is called `ppp0'. Use
- ifconfig to find out, and adjust to taste.
- # ipchains -P forward DENY
- # ipchains -A forward -i ppp0 -j MASQ
- # echo 1 > /proc/sys/net/ipv4/ip_forward
-
-
-
- 3.2. Gratuitous Promotion: WatchGuard Rules
-
- You can buy off-the-shelf firewalls. An excellent one is WatchGuard's
- FireBox. It's excellent because I like it, it's secure, it's Linux-
- based, and because they funded the maintenance of ipchains as well as
- the new firewalling code (for 2.4). In short, WatchGuard were paying
- for me to eat while I work for you. So please consider their stuff.
-
- http://www.watchguard.com
-
-
- 3.3. Common Firewall-like Setups
-
- You run littlecorp.com. You have an internal network, and a single
- dialup (PPP) connection to the Internet (firewall.littlecorp.com which
- is 1.2.3.4). You run Ethernet on your local network, and your
- personal machine is called "myhost".
-
-
- This section will illustrate the different arrangement which are
- common. Read carefully, because they are each subtly different.
-
-
- 3.3.1. Private Network: Traditional Proxies
-
- In this scenario, packets from the private network never traverse the
- Internet, and vice versa. The IP addresses of the private network
- should be assigned from the RFC1918 Address Allocation for Private
- Internets (ie. 10.*.*.*, 172.16.*.*-172.31.*.* or 192.168.*.*).
-
-
- The only way things ever connect to the Internet is by connecting to
- the firewall, which is the only machine on both networks which
- connects onwards. You run a program (on the firewall) called a proxy
- to do this (there are proxies for FTP, web access, telnet, RealAudio,
- Usenet News and other services). See the Firewall HOWTO.
-
-
- Any services you wish the Internet to access must be on the firewall.
- (But see ``Limited Internal Services'' below).
-
-
- Example: Allowing web access from private network to the Internet.
-
- 1. The private network is assigned 192.168.1.* addresses, with myhost
- being 192.168.1.100, and the firewall's Ethernet interface being
- assigned 192.168.1.1.
-
- 2. A web proxy (eg. "squid") is installed and configured on the
- firewall, say running on port 8080.
-
- 3. Netscape on the private network is configured to use the firewall
- port 8080 as a proxy.
-
- 4. DNS does not need to be configured on the private network.
-
- 5. DNS does need to be configured on the firewall.
-
- 6. No default route (aka gateway) needs to be configured on the
- private network.
-
-
- Netscape on myhost reads http://slashdot.org.
-
- 1. Netscape connects to the firewall port 8080, using port 1050 on
- myhost. It asks for the web page of "http://slashdot.org".
-
- 2. The proxy looks up the name "slashdot.org", and gets
- 207.218.152.131. It then opens a connection to that IP address
- (using port 1025 on the firewall's external interface), and asks
- the web server (port 80) for the web page.
-
- 3. As it receives the web page from its connection to the web server,
- it copies the data to the connection from Netscape.
-
- 4. Netscape renders the page.
-
- ie. From slashdot.org's point of view, the connection is made from
- 1.2.3.4 (firewall's PPP interface) port 1025 to 207.218.152.131
- (slashdot.org) port 80. From myhost's point of view, the connection
- is made from 192.168.1.100 (myhost) port 1050, to 192.168.1.1
- (firewall's Ethernet interface) port 8080.
-
-
-
- 3.3.2. Private Network: Transparent Proxies
-
- In this scenario, packets from the private network never traverse the
- Internet, and vice versa. The IP addresses of the private network
- should be assigned from the RFC1918 Address Allocation for Private
- Internets (ie. 10.*.*.*, 172.16.*.*-172.31.*.* or 192.168.*.*).
-
-
- The only way things ever connect to the Internet is by connecting to
- the firewall, which is the only machine on both networks, which
- connects onwards. You run a program (on the firewall) called a
- transparent proxy to do this; the kernel sends outgoing packets to the
- transparent proxy instead of sending them onwards (ie. it bastardizes
- routing).
-
-
- Transparent proxying means that the clients don't need to know there
- is a proxy involved.
-
-
- Any services you wish the Internet to access must be on the firewall.
- (But see ``Limited Internal Services'' below).
-
-
- Example: Allowing web access from private network to the Internet.
-
- 1. The private network is assigned 192.168.1.* addresses, with myhost
- being 192.168.1.100, and the firewall's Ethernet interface being
- assigned 192.168.1.1.
-
- 2. A transparent web proxy (I believe there are patches for squid to
- allow it to operate in this manner, or try "transproxy") is
- installed and configured on the firewall, say running on port 8080.
-
- 3. The kernel is told to redirect connections to port 80 to the proxy,
- using ipchains.
-
- 4. Netscape on the private network is configured to connect directly.
-
- 5. DNS needs to be configured on the private network (ie. you need to
- run a DNS server as a proxy on the firewall).
-
- 6. The default route (aka gateway) needs to be configured on the
- private network, to send packets to the firewall.
-
-
- Netscape on myhost reads http://slashdot.org.
-
- 1. Netscape looks up the name "slashdot.org", and gets
- 207.218.152.131. It then opens a connection to that IP address,
- using local port 1050, and asks the web server (port 80) for the
- web page.
-
- 2. As the packets from myhost (port 1050) to slashdot.org (port 80)
- pass through the firewall, they are redirected to the waiting
- transparent proxy on port 8080. The transparent proxy opens a
- connection (using local port 1025) to 207.218.152.131 port 80
- (which is where the original packets were going).
-
- 3. As the proxy receives the web page from its connection to the web
- server, it copies the data to the connection from Netscape.
-
- 4. Netscape renders the page.
-
- ie. From slashdot.org's point of view, the connection is made from
- 1.2.3.4 (firewall's PPP interface) port 1025 to 207.218.152.131
- (slashdot.org) port 80. From myhost's point of view, the connection
- is made from 192.168.1.100 (myhost) port 1050, to 207.218.152.131
- (slashdot.org) port 80, but it's actually talking to the transparent
- proxy.
-
-
- 3.3.3. Private Network: Masquerading
-
- In this scenario, packets from the private network never traverse the
- Internet without special treatment, and vice versa. The IP addresses
- of the private network should be assigned from the RFC1918 Address
- Allocation for Private Internets (ie. 10.*.*.*, 172.16.*.*-172.31.*.*
- or 192.168.*.*).
-
-
- Instead of using a proxy, we use a special kernel facility called
- "masquerading". Masquerading rewrites packets as they pass through
- the firewall, so that they always seem to come from the firewall
- itself. It then rewrites the responses so that they look like they
- are going to the original recipient.
-
-
- Masquerading has separate modules to handle "tricky" protocols, such
- as FTP, RealAudio, Quake, etc. For really hard-to-handle protocols,
- the "auto forwarding" facility can handle some of them by
- automatically setting up port forwarding for related sets of ports:
- look for ``ipportfw'' (2.0 kernels) or ``ipmasqadm'' (2.1 kernels).
-
-
- Any services you wish the Internet to access must be on the firewall.
- (But see ``Limited Internal Services'' below).
-
-
- Example: Allowing web access from private network to the Internet.
-
- 1. The private network is assigned 192.168.1.* addresses, with myhost
- being 192.168.1.100, and the firewall's Ethernet interface being
- assigned 192.168.1.1.
-
- 2. The firewall is set up to masquerade any packets coming from the
- private network and going to port 80 on an Internet host.
-
- 3. Netscape is configured to connect directly.
-
- 4. DNS must be configured correctly on the private network.
-
- 5. The firewall should be the default route (aka gateway) for the
- private network.
-
- Netscape on myhost reads http://slashdot.org.
-
- 1. Netscape looks up the name "slashdot.org", and gets
- 207.218.152.131. It then opens a connection to that IP address,
- using local port 1050, and asks the web server (port 80) for the
- web page.
-
- 2. As the packets from myhost (port 1050) to slashdot.org (port 80)
- pass through the firewall, they are rewritten to come from the PPP
- interface of the firewall, port 65000. The firewall has a valid
- Internet address (1.2.3.4) so reply packets from slashdot.org get
- routed back OK.
-
- 3. As packets from slashdot.org (port 80) to firewall.littlecorp.com
- (port 65000) come in, they are rewritten to go to myhost, port
- 1050. This is the real magic of masquerading: it remembers when it
- rewrites outgoing packets to it can write them back as replies come
- in.
-
- 4. Netscape renders the page.
-
- ie. From the slashdot.org's point of view, the connection is made
- from 1.2.3.4 (firewall's PPP interface) port 65000 to 207.218.152.131
- (slashdot.org) port 80. From the myhost's point of view, the
- connection is made from 192.168.1.100 (myhost) port 1050, to
- 207.218.152.131 (slashdot.org) port 80.
-
-
-
- 3.3.4. Public Network
-
- In this scenario, your personal network is a part of the Internet:
- packets can flow without change across both networks. The IP
- addresses of the internal network must be assigned by applying for a
- block of IP addresses, so the rest of the network will know how to get
- packets to you. This implies a permanent connection.
-
-
- In this role, packet filtering is used to restrict which packets can
- be forwarded between your network and the rest of the Internet, eg. to
- restrict the rest of the Internet to only accessing your internal web
- servers.
-
-
- Example: Allowing web access from private network to the Internet.
-
- 1. Your internal network is assigned according to the IP address block
- you have registered, (say 1.2.3.*).
-
- 2. The firewall is set up to allow all traffic.
-
- 3. Netscape is configured to connect directly.
-
- 4. DNS must be configured correctly on your network.
-
-
- 5. The firewall should be the default route (aka gateway) for the
- private network.
-
- Netscape on myhost reads http://slashdot.org.
-
- 1. Netscape looks up the name "slashdot.org", and gets
- 207.218.152.131. It then opens a connection to that IP address,
- using local port 1050, and asks the web server (port 80) for the
- web page.
-
- 2. Packets pass through your firewall, just as they pass through
- several other routers between you and slashdot.org.
-
- 3. Netscape renders the page.
-
- ie. There is only one connection: from 1.2.3.100 (myhost) port 1050,
- to 207.218.152.131 (slashdot.org) port 80.
-
-
- 3.3.5. Limited Internal Services
-
- There are a few tricks you can pull to allow the Internet to access
- your internal services, rather than running the services on the
- firewall. These will work with either a proxy or masquerading based
- approach for external connections.
-
-
- The simplest approach is to run a "redirector", which is a poor-man's
- proxy which waits for a connection on a given port, and then open a
- connection a fixed internal host and port, and copies data between the
- two connections. An example of this is the "redir" program. From the
- Internet point of view, the connection is made to your firewall. From
- your internal server's point of view, the connection is made from the
- internal interface of the firewall to the server.
-
-
- Another approach (which requires a 2.0 kernel patched for ipportfw, or
- a 2.1 or later kernel) is to use port forwarding in the kernel. This
- does the same job as "redir" in a different way: the kernel rewrites
- packets as they pass through, changing their destination address and
- ports to point them at an internal host and port. From the Internet's
- point of view, the connection is made to your firewall. From your
- internal server's point of view, a direct connection is made from the
- Internet host to the server.
-
-
- 3.4. More Information on Masquerading
-
- David Ranch has written an excellent new HOWTO on Masquerading, which
- has a large amount of overlap with this HOWTO. You can currently find
- that HOWTO at
-
- http://www.linuxdoc.org/HOWTO/IP-Masquerade-HOWTO.html
-
-
- The official Masquerading home page is at
-
- http://ipmasq.cjb.net
-
-
-
- 4. IP Firewalling Chains
-
- This section describes all you really need to know to build a packet
- filter that meets your needs.
-
- 4.1. How Packets Traverse The Filters
-
- The kernel starts with three lists of rules; these lists are called
- firewall chains or just chains. The three chains are called input,
- output and forward. When a packet comes in (say, through the Ethernet
- card) the kernel uses the input chain to decide its fate. If it
- survives that step, then the kernel decides where to send the packet
- next (this is called routing). If it is destined for another machine,
- it consults the forward chain. Finally, just before a packet is to go
- out, the kernel consults the output chain.
-
-
- A chain is a checklist of rules. Each rule says `if the packet header
- looks like this, then here's what to do with the packet'. If the rule
- doesn't match the packet, then the next rule in the chain is
- consulted. Finally, if there are no more rules to consult, then the
- kernel looks at the chain policy to decide what to do. In a security-
- conscious system, this policy usually tells the kernel to reject or
- deny the packet.
-
-
- For ASCII-art fans, this shown the complete path of a packet coming
- into a machine.
-
-
- ----------------------------------------------------------------
- | ACCEPT/ lo interface |
- v REDIRECT _______ |
- --> C --> S --> ______ --> D --> ~~~~~~~~ -->|forward|----> _______ -->
- h a |input | e {Routing } |Chain | |output |ACCEPT
- e n |Chain | m {Decision} |_______| --->|Chain |
- c i |______| a ~~~~~~~~ | | ->|_______|
- k t | s | | | | |
- s y | q | v | | |
- u | v e v DENY/ | | v
- m | DENY/ r Local Process REJECT | | DENY/
- | v REJECT a | | | REJECT
- | DENY d --------------------- |
- v e -----------------------------
- DENY
-
-
- Here is a blow-by-blow description of each stage:
-
-
- Checksum:
- This is a test that the packet hasn't been corrupted in some
- way. If it has, it is denied.
-
-
- Sanity:
- There is actually one of these sanity checks before each
- firewall chain, but the input chain's is the most important.
- Some malformed packets might confuse the rule-checking code, and
- these are denied here (a message is printed to the syslog if
- this happens).
-
-
- input chain:
- This is the first firewall chain against which the packet will
- be tested. If the verdict of the chain is not DENY or REJECT,
- the packet continues on.
-
-
- Demasquerade:
- If the packet is a reply to a previously masqueraded packet, it
- is demasqueraded, and skips straight to the output chain. If
- you don't use IP Masquerading, you can mentally erase this from
- the diagram.
-
-
- Routing decision:
- The destination field is examined by the routing code, to decide
- if this packet should go to a local process (see Local process
- below) or forwarded to a remote machine (see forward chain
- below).
-
-
- Local process:
- A process running on the machine can receive packets after the
- Routing Decision step, and can send packets (which go through
- the Routing Decision step, then traverse the output chain).
-
-
- lo interface:
- If packets from a local process are destined for a local
- process, they will go through the output chain with interface
- set to `lo', then return through the input chain with interface
- also `lo'. The lo interface is usually called the loopback
- interface.
-
-
- local:
- If the packet was not created by a local process, then the
- forward chain is checked, otherwise the packet goes to the
- output chain.
-
-
- forward chain:
- This chain is traversed for any packets which are attempting to
- pass through this machine to another.
-
-
- output chain:
- This chain is traversed for all packets just before they are
- sent out.
-
-
- 4.1.1. Using ipchains
-
- First, check that you have the version of ipchains that this document
- refers to:
-
-
-
- $ ipchains --version
- ipchains 1.3.9, 17-Mar-1999
-
-
-
- Note that I recommend 1.3.4 (which has no long options, like
- `--sport'), or 1.3.8 or above; these are very stable.
-
-
- ipchains has a fairly detailed manual page (man ipchains), and if you
- need more detail on particulars, you can check out the programming
- interface (man 4 ipfw), or the file net/ipv4/ip_fw.c in the 2.1.x
- kernel source, which is (obviously) authoritative.
-
-
- There is also an excellent quick reference card by Scott Bronson in
- the source package, in both A4 and US Letter PostScript(TM).
-
-
- There are several different things you can do with ipchains. First
- the operations to manage whole chains. You start with three built-in
- chains input, output and forward which you can't delete.
-
-
- 1. Create a new chain (-N).
-
- 2. Delete an empty chain (-X).
-
- 3. Change the policy for a built-in chain. (-P).
-
- 4. List the rules in a chain (-L).
-
- 5. Flush the rules out of a chain (-F).
-
- 6. Zero the packet and byte counters on all rules in a chain (-Z).
-
- There are several ways to manipulate rules inside a chain:
-
-
- 1. Append a new rule to a chain (-A).
-
- 2. Insert a new rule at some position in a chain (-I).
-
- 3. Replace a rule at some position in a chain (-R).
-
- 4. Delete a rule at some position in a chain (-D).
-
- 5. Delete the first rule that matches in a chain (-D).
-
- There are a few operations for masquerading, which are in ipchains for
- want of a good place to put them:
-
-
- 1. List the currently masqueraded connections (-M -L).
-
- 2. Set masquerading timeout values (-M -S). (But see ``I can't set
- masquerading timeouts!'').
-
- The final (and perhaps the most useful) function allows you to check
- what would happen to a given packet if it were to traverse a given
- chain.
-
-
- 4.1.2. What You'll See When Your Computer Starts Up
-
- Before any ipchains commands have been run (be careful: some
- distributions run ipchains in their initialization scripts), there
- will be no rules in any of the built-in chains (`input', `forward' and
- `output'), and each of the chains will have a policy of ACCEPT. This
- is as wide-open as you can get.
-
-
- 4.1.3. Operations on a Single Rule
-
- This is the bread-and-butter of ipchains; manipulating rules. Most
- commonly, you will probably use the append (-A) and delete (-D)
- commands. The others (-I for insert and -R for replace) are simple
- extensions of these concepts.
-
-
-
- Each rule specifies a set of conditions the packet must meet, and what
- to do if it meets them (a `target'). For example, you might want to
- deny all ICMP packets coming from the IP address 127.0.0.1. So in
- this case our conditions are that the protocol must be ICMP and that
- the source address must be 127.0.0.1. Our target is `DENY'.
-
-
- 127.0.0.1 is the `loopback' interface, which you will have even if you
- have no real network connection. You can use the `ping' program to
- generate such packets (it simply sends an ICMP type 8 (echo request)
- which all cooperative hosts should obligingly respond to with an ICMP
- type 0 (echo reply) packet). This makes it useful for testing.
-
-
-
- # ping -c 1 127.0.0.1
- PING 127.0.0.1 (127.0.0.1): 56 data bytes
- 64 bytes from 127.0.0.1: icmp_seq=0 ttl=64 time=0.2 ms
-
- --- 127.0.0.1 ping statistics ---
- 1 packets transmitted, 1 packets received, 0% packet loss
- round-trip min/avg/max = 0.2/0.2/0.2 ms
- # ipchains -A input -s 127.0.0.1 -p icmp -j DENY
- # ping -c 1 127.0.0.1
- PING 127.0.0.1 (127.0.0.1): 56 data bytes
-
- --- 127.0.0.1 ping statistics ---
- 1 packets transmitted, 0 packets received, 100% packet loss
- #
-
-
-
- You can see here that the first ping succeeds (the `-c 1' tells ping
- to only send a single packet).
-
-
- Then we append (-A) to the `input' chain, a rule specifying that for
- packets from 127.0.0.1 (`-s 127.0.0.1') with protocol ICMP (`-p ICMP')
- we should jump to DENY (`-j DENY').
-
-
- Then we test our rule, using the second ping. There will be a pause
- before the program gives up waiting for a response that will never
- come.
-
-
- We can delete the rule in one of two ways. Firstly, since we know
- that it is the only rule in the input chain, we can use a numbered
- delete, as in:
-
-
- # ipchains -D input 1
- #
-
-
-
- To delete rule number 1 in the input chain.
-
-
- The second way is to mirror the -A command, but replacing the -A with
- -D. This is useful when you have a complex chain of rules and you
- don't want to have to count them to figure out that it's rule 37 that
- you want to get rid of. In this case, we would use:
-
- # ipchains -D input -s 127.0.0.1 -p icmp -j DENY
- #
-
-
-
- The syntax of -D must have exactly the same options as the -A (or -I
- or -R) command. If there are multiple identical rules in the same
- chain, only the first will be deleted.
-
-
- 4.1.4. Filtering Specifications
-
- We have seen the use of `-p' to specify protocol, and `-s' to specify
- source address, but there are other options we can use to specify
- packet characteristics. What follows is an exhaustive compendium.
-
-
- 4.1.4.1. Specifying Source and Destination IP Addresses
-
- Source (-s) and destination (-d) IP addresses can be specified in four
- ways. The most common way is to use the full name, such as
- `localhost' or `www.linuxhq.com'. The second way is to specify the IP
- address such as `127.0.0.1'.
-
-
- The third and fourth ways allow specification of a group of IP
- addresses, such as `199.95.207.0/24' or `199.95.207.0/255.255.255.0'.
- These both specify any IP address from 199.95.207.0 to 199.95.207.255
- inclusive; the digits after the `/' tell which parts of the IP address
- are significant. `/32' or `/255.255.255.255' is the default (match
- all of the IP address). To specify any IP address at all `/0' can be
- used, like so:
-
-
- # ipchains -A input -s 0/0 -j DENY
- #
-
-
-
- This is rarely used, as the effect above is the same as not specifying
- the `-s' option at all.
-
-
- 4.1.4.2. Specifying Inversion
-
- Many flags, including the `-s' and `-d' flags can have their arguments
- preceded by `!' (pronounced `not') to match addresses NOT equal to the
- ones given. For example. `-s ! localhost' matches any packet not
- coming from localhost.
-
-
- Don't forget the spaces around the `!': they really are needed.
-
-
- 4.1.4.3. Specifying Protocol
-
- The protocol can be specified with the `-p' flag. Protocol can be a
- number (if you know the numeric protocol values for IP) or a name for
- the special cases of `TCP', `UDP' or `ICMP'. Case doesn't matter, so
- `tcp' works as well as `TCP'.
-
-
- The protocol name can be prefixed by a `!', to invert it, such as `-p
- ! TCP'.
- 4.1.4.3.1. Specifying UDP and TCP Ports
-
- For the special case where a protocol of TCP or UDP is specified,
- there can be an extra argument indicating the TCP or UDP port, or an
- (inclusive) range of ports (but see ``Handling Fragments'' below). A
- range is represented using a `:' character, such as `6000:6010', which
- covers 11 port numbers, from 6000 to 6010 inclusive. If the lower
- bound is omitted, it defaults to 0. If the upper bound is omitted, it
- defaults to 65535. So to specify TCP connections coming from ports
- under 1024, the syntax would be as `-p TCP -s 0.0.0.0/0 :1023'. Port
- numbers can be specified by name, eg. `www'.
-
-
- Note that the port specification can be preceded by a `!', which
- inverts it. So to specify every TCP packet BUT a WWW packet, you
- would specify
-
- -p TCP -d 0.0.0.0/0 ! www
-
-
-
- It is important to realize that the specification
-
-
- -p TCP -d ! 192.168.1.1 www
-
-
-
- is very different from
-
- -p TCP -d 192.168.1.1 ! www
-
-
-
- The first specifies any TCP packet to the WWW port on any machine but
- 192.168.1.1. The second specifies any TCP connection to any port on
- 192.168.1.1 but the WWW port.
-
-
- Finally, this case means not the WWW port and not 192.168.1.1:
-
- -p TCP -d ! 192.168.1.1 ! www
-
-
-
- 4.1.4.3.2. Specifying ICMP Type and Code
-
- ICMP also allows an optional argument, but as ICMP doesn't have ports,
- (ICMP has a type and a code) they have a different meaning.
-
-
- You can specify them as ICMP names (use ipchains -h icmp to list the
- names) after the `-s' option, or as a numeric ICMP type and code,
- where the type follows the `-s' option and the code follows the `-d'
- option.
-
-
- The ICMP names are fairly long: you only need use enough letters to
- make the name distinct from any other.
-
-
- Here is a small table of some of the most common ICMP packets:
-
-
-
- Number Name Required by
-
- 0 echo-reply ping
- 3 destination-unreachable Any TCP/UDP traffic.
- 5 redirect routing if not running routing daemon
- 8 echo-request ping
- 11 time-exceeded traceroute
-
-
-
- Note that the ICMP names cannot be preceeded by `!' at the moment.
-
-
- DO NOT DO NOT DO NOT block all ICMP type 3 messages! (See ``ICMP
- Packets'' below).
-
-
- 4.1.4.4. Specifying an Interface
-
- The `-i' option specifies the name of an interface to match. An
- interface is the physical device the packet came in on, or is going
- out on. You can use the ifconfig command to list the interfaces which
- are `up' (ie. working at the moment).
-
-
- The interface for incoming packets (ie. packets traversing the input
- chain) is considered to be the interface they came in on. Logically,
- the interface for outgoing packets (packets traversing the output
- chain) is the interface they will go out on. The interface for
- packets traversing the forward chain is also the interface they will
- go out on; a fairly arbitrary decision it seems to me.
-
-
- It is perfectly legal to specify an interface that currently does not
- exist; the rule will not match anything until the interface comes up.
- This is extremely useful for dial-up PPP links (usually interface
- ppp0) and the like.
-
-
- As a special case, an interface name ending with a `+' will match all
- interfaces (whether they currently exist or not) which begin with that
- string. For example, to specify a rule which matches all PPP
- interfaces, the -i ppp+ option would be used.
-
-
- The interface name can be preceded by a `!' to match a packet which
- does NOT match the specified interface(s).
-
-
- 4.1.4.5. Specifying TCP SYN Packets Only
-
- It is sometimes useful to allow TCP connections in one direction, but
- not the other. For example, you might want to allow connections to an
- external WWW server, but not connections from that server.
-
-
- The naive approach would be to block TCP packets coming from the
- server. Unfortunately, TCP connections require packets going in both
- directions to work at all.
-
-
- The solution is to block only the packets used to request a
- connection. These packets are called SYN packets (ok, technically
- they're packets with the SYN flag set, and the FIN and ACK flags
- cleared, but we call them SYN packets). By disallowing only these
- packets, we can stop attempted connections in their tracks.
-
-
- The `-y' flag is used for this: it is only valid for rules which
- specify TCP as their protocol. For example, to specify TCP connection
- attempts from 192.168.1.1:
-
- -p TCP -s 192.168.1.1 -y
-
-
-
- Once again, this flag can be inverted by preceding it with a `!',
- which means every packet other than the connection initiation.
-
-
- 4.1.4.6. Handling Fragments
-
- Sometimes a packet is too large to fit down a wire all at once. When
- this happens, the packet is divided into fragments, and sent as
- multiple packets. The other end reassembles the fragments to
- reconstruct the whole packet.
-
-
- The problem with fragments is that some of the specifications listed
- above (in particular, source port, destinations port, ICMP type, ICMP
- code, or TCP SYN flag) require the kernel to peek at the start of the
- packet, which is only contained in the first fragment.
-
-
- If your machine is the only connection to an external network, then
- you can tell the Linux kernel to reassemble all fragments which pass
- through it, by compiling the kernel with IP: always defragment set to
- `Y'. This sidesteps the issue neatly.
-
-
- Otherwise, it is important to understand how fragments get treated by
- the filtering rules. Any filtering rule that asks for information we
- don't have will not match. This means that the first fragment is
- treated like any other packet. Second and further fragments won't be.
- Thus a rule -p TCP -s 192.168.1.1 www (specifying a source port of
- `www') will never match a fragment (other than the first fragment).
- Neither will the opposite rule -p TCP -s 192.168.1.1 ! www.
-
-
- However, you can specify a rule specifically for second and further
- fragments, using the `-f' flag. Obviously, it is illegal to specify a
- TCP or UDP port, ICMP type, ICMP code or TCP SYN flag in such a
- fragment rule.
-
-
- It is also legal to specify that a rule does not apply to second and
- further fragments, by preceding the `-f' with `!'.
-
-
- Usually it is regarded as safe to let second and further fragments
- through, since filtering will effect the first fragment, and thus
- prevent reassembly on the target host, however, bugs have been known
- to allow crashing of machines simply by sending fragments. Your call.
-
-
- Note for network-heads: malformed packets (TCP, UDP and ICMP packets
- too short for the firewalling code to read the ports or ICMP code and
- type) are treated as fragments as well. Only TCP fragments starting
- at position 8 are explicitly dropped by the firewall code (a message
- should appear in the syslog if this occurs).
- As an example, the following rule will drop any fragments going to
- 192.168.1.1:
-
-
-
- # ipchains -A output -f -d 192.168.1.1 -j DENY
- #
-
-
-
- 4.1.5. Filtering Side Effects
-
- OK, so now we know all the ways we can match a packet using a rule.
- If a packet matches a rule, the following things happen:
-
-
- 1. The byte counter for that rule is increased by the size of the
- packet (header and all).
-
- 2. The packet counter for that rule is incremented.
-
- 3. If the rule requests it, the packet is logged.
-
- 4. If the rule requests it, the packet's Type Of Service field is
- changed.
-
- 5. If the rule requests it, the packet is marked (not in 2.0 kernel
- series).
-
- 6. The rule target is examined to decide what to do to the packet
- next.
-
-
- For variety, I'll address these in order of importance.
-
-
- 4.1.5.1. Specifying a Target
-
- A target tells the kernel what to do with a packet that matches a
- rule. ipchains uses `-j' (think `jump-to') for the target
- specification. The target name must be less than 8 letters, and case
- matters: "RETURN" and "return" are completely different.
-
-
- The simplest case is when there is no target specified. This type of
- rule (often called an `accounting' rule) is useful for simply counting
- a certain type of packet. Whether this rule matches or not, the
- kernel simply examines the next rule in the chain. For example, to
- count the number of packets from 192.168.1.1, we could do this:
-
-
- # ipchains -A input -s 192.168.1.1
- #
-
-
-
- (Using `ipchains -L -v' we can see the byte and packet counters
- associated with each rule).
-
-
-
- There are six special targets. The first three, ACCEPT, REJECT and
- DENY are fairly simple. ACCEPT allows the packet through. DENY drops
- the packet as if it had never been received. REJECT drops the packet,
- but (if it's not an ICMP packet) generates an ICMP reply to the source
- to tell it that the destination was unreachable.
-
-
- The next one, MASQ tells the kernel to masquerade the packet. For
- this to work, your kernel needs to be compiled with IP Masquerading
- enabled. For details on this, see the Masquerading-HOWTO and the
- Appendix ``Differences between ipchains and ipfwadm''. This target is
- only valid for packets traversing the forward chain.
-
-
- The other major special target is REDIRECT which tells the kernel to
- send a packet to a local port instead of wherever it was heading.
- This can only be specified for rules specifying TCP or UDP as their
- protocol. Optionally, a port (name or number) can be specified
- following `-j REDIRECT' which will cause the packet to be redirected
- to that particular port, even if it was addressed to another port.
- This target is only valid for packets traversing the input chain.
-
-
- The final special target is RETURN which is identical to falling off
- the end of the chain immediately. (See ``Setting Policy'' below).
-
-
- Any other target indicates a user-defined chain (as described in
- ``Operations on an Entire Chain'' below). The packet will begin
- traversing the rules in that chain. If that chain doesn't decide the
- fate of the packet, then once traversal on that chain has finished,
- traversal resumes on the next rule in the current chain.
-
-
- Time for more ASCII art. Consider two (silly) chains: input (the
- built-in chain) and Test (a user-defined chain).
-
-
- `input' `Test'
- ---------------------------- ----------------------------
- | Rule1: -p ICMP -j REJECT | | Rule1: -s 192.168.1.1 |
- |--------------------------| |--------------------------|
- | Rule2: -p TCP -j Test | | Rule2: -d 192.168.1.1 |
- |--------------------------| ----------------------------
- | Rule3: -p UDP -j DENY |
- ----------------------------
-
-
-
- Consider a TCP packet coming from 192.168.1.1, going to 1.2.3.4. It
- enters the input chain, and gets tested against Rule1 - no match.
- Rule2 matches, and its target is Test, so the next rule examined is
- the start of Test. Rule1 in Test matches, but doesn't specify a
- target, so the next rule is examined, Rule2. This doesn't match, so
- we have reached the end of the chain. We return to the input chain,
- where we had just examined Rule2, so we now examine Rule3, which
- doesn't match either.
-
-
- So the packet path is:
-
-
-
- v __________________________
- `input' | / `Test' v
- ------------------------|--/ -----------------------|----
- | Rule1 | /| | Rule1 | |
- |-----------------------|/-| |----------------------|---|
- | Rule2 / | | Rule2 | |
- |--------------------------| -----------------------v----
- | Rule3 /--+___________________________/
- ------------------------|---
- v
-
-
-
- See the section ``How to Organise Your Firewall Rules'' for ways to
- use user-defined chains effectively.
-
-
- 4.1.5.2. Logging Packets
-
- This is a side effect that matching a rule can have; you can have the
- matching packet logged using the `-l' flag. You will usually not want
- this for routine packets, but it is a useful feature if you want to
- look for exceptional events.
-
-
- The kernel logs this information looking like:
-
-
-
- Packet log: input DENY eth0 PROTO=17 192.168.2.1:53 192.168.1.1:1025
- L=34 S=0x00 I=18 F=0x0000 T=254
-
-
-
- This log message is designed to be terse, and contain technical
- information useful only to networking gurus, but it can be useful to
- the rest of us. It breaks down like so:
-
-
- 1. `input' is the chain which contained the rule which matched the
- packet, causing the log message.
-
- 2. `DENY' is what the rule said to do to the packet. If this is `-'
- then the rule didn't effect the packet at all (an accounting rule).
-
- 3. `eth0' is the interface name. Because this was the input chain, it
- means that the packet came in `eth0'.
-
- 4. `PROTO=17' means that the packet was protocol 17. A list of
- protocol numbers is given in `/etc/protocols'. The most common are
- 1 (ICMP), 6 (TCP) and 17 (UDP).
-
- 5. `192.168.2.1' means that the packet's source IP address was
- 192.168.2.1.
-
- 6. `:53' means that the source port was port 53. Looking in
- `/etc/services' shows that this is the `domain' port (ie. this is
- probably an DNS reply). For UDP and TCP, this number is the source
- port. For ICMP, it's the ICMP type. For others, it will be 65535.
-
- 7. `192.168.1.1' is the destination IP address.
-
- 8. `:1025' means that the destination port was 1025. For UDP and TCP,
- this number is the destination port. For ICMP, it's the ICMP code.
- For others, it will be 65535.
-
- 9. `L=34' means that packet was a total of 34 bytes long.
-
- 10.
- `S=0x00' means the Type of Service field (divide by 4 to get the
- Type of Service as used by ipchains).
-
- 11.
- `I=18' is the IP ID.
-
- 12.
- `F=0x0000' is the 16-bit fragment offset plus flags. A value
- starting with `0x4' or `0x5' means that the Don't Fragment bit is
- set. `0x2' or `0x3' means the `More Fragments' bit is set; expect
- more fragments after this. The rest of the number is the offset of
- this fragment, divided by 8.
-
- 13.
- `T=254' is the Time To Live of the packet. One is subtracted from
- this value for every hop, and it usually starts at 15 or 255.
-
- 14.
- `(#5)' there may be a final number in brackets on more recent
- kernels (perhaps after 2.2.9). This is the rule number which
- caused the packet log.
-
-
- On standard Linux systems, this kernel output is captured by klogd
- (the kernel logging daemon) which hands it to syslogd (the system
- logging daemon). The `/etc/syslog.conf' controls the behaviour of
- syslogd, by specifying a destination for each `facility' (in our case,
- the facility is "kernel") and `level' (for ipchains, the level used is
- "info").
-
-
- For example, my (Debian) /etc/syslog.conf contains two lines which
- match `kern.info':
-
-
-
- kern.* -/var/log/kern.log
- *.=info;*.=notice;*.=warn;\
- auth,authpriv.none;\
- cron,daemon.none;\
- mail,news.none -/var/log/messages
-
-
-
- These mean that the messags are duplicated in `/var/log/kern.log' and
- `/var/log/messages'. For more details, see `man syslog.conf'.
-
-
- 4.1.5.3. Manipulating the Type Of Service
-
- There are four seldom-used bits in the IP header, called the Type of
- Service (TOS) bits. They effect the way packets are treated; the four
- bits are "Minimum Delay", "Maximum Throughput", "Maximum Reliability"
- and "Minimum Cost". Only one of these bits is allowed to be set. Rob
- van Nieuwkerk, the author of the TOS-mangling code, puts it as
- follows:
-
-
- Especially the "Minimum Delay" is important for me. I
- switch it on for "interactive" packets in my upstream
- (Linux) router. I'm behind a 33k6 modem link. Linux prior
- itizes packets in 3 queues. This way I get acceptable
- interactive performance while doing bulk downloads at the
- same time. (It could even be better if there wasn't such a
- big queue in the serial driver, but latency is kept down 1.5
- seconds now).
-
-
-
- Note: obviously, you have no control over incoming packets; you can
- only control the priority of packets leaving your box. To negotiate
- priorities with the other end, a protocol like RSVP (which I know
- nothing about, so don't ask me) must be used.
-
-
- The most common use is to set telnet & ftp control connections to
- "Minimum Delay" and FTP data to "Maximum Throughput". This would be
- done as follows:
-
-
-
- ipchains -A output -p tcp -d 0.0.0.0/0 telnet -t 0x01 0x10
- ipchains -A output -p tcp -d 0.0.0.0/0 ftp -t 0x01 0x10
- ipchains -A output -p tcp -s 0.0.0.0/0 ftp-data -t 0x01 0x08
-
-
-
- The `-t' flag takes two extra parameters, both in hexadecimal. These
- allow complex twiddling of the TOS bits: the first mask is ANDed with
- the packet's current TOS, and then the second mask is XORed with it.
- If this is too confusing, just use the following table:
-
-
-
- TOS Name Value Typical Uses
-
- Minimum Delay 0x01 0x10 ftp, telnet
- Maximum Throughput 0x01 0x08 ftp-data
- Maximum Reliability 0x01 0x04 snmp
- Minimum Cost 0x01 0x02 nntp
-
-
-
- Andi Kleen goes on to point out the following (mildly edited for
- posterity):
-
- Maybe it would be useful to add an reference to the txqueue
- len parameter of ifconfig to the discussion of TOS bits. The
- default device queue length is tuned for ethernet cards, on
- modems it is too long and makes the 3 band scheduler (which
- queues based on TOS) work suboptimally. It is a good idea to
- set it to a value between 4-10 on modem or single b channel
- ISDN links: on bundled devices a longer queue is needed.
- This is a 2.0 and 2.1 problem, but in 2.1 it is a ifconfig
- flag (with recent nettools), while in 2.0 it requires source
- patches in the device drivers to change.
-
-
- So, to see maximal benifits of TOS manipulation for modem PPP links,
- do `ifconfig $1 txqueuelen' in your /etc/ppp/ip-up script. The number
- to use depends on the modem speed and the amount of buffering in the
- modem; here's Andi setting me straight again:
-
- The best value for a given configuration needs experiment.
- If the queues are too short on a router then packets will
- get dropped. Also of course one gets benefits even without
- TOS rewriting, just that TOS rewriting helps to give the
- benefits to non cooperating programs (but all standard linux
- programs are cooperating).
-
-
-
- 4.1.5.4. Marking a Packet
-
- This allows complex and powerful interactions with Alexey Kuznetsov's
- new Quality of Service implementation, as well as the mark-based
- forwarding in later 2.1 series kernels. More news as it comes to
- hand. This option is ignored altogether in the 2.0 kernel series.
-
-
- 4.1.5.5. Operations on an Entire Chain
-
- A very useful feature of ipchains is the ability to group related
- rules into chains. You can call the chains whatever you want, as long
- as the names don't clash with the built-in chains (input, output and
- forward) or the targets (MASQ, REDIRECT, ACCEPT, DENY, REJECT or
- RETURN). I suggest avoiding upper-case labels entirely, since I may
- use these for future extensions. The chain name can be up to 8
- characters long.
-
-
- 4.1.5.6. Creating a New Chain
-
- Let's create a new chain. Because I am such an imaginative fellow,
- I'll call it test.
-
-
-
- # ipchains -N test
- #
-
-
-
- It's that simple. Now you can put rules in it as detailed above.
-
-
- 4.1.5.7. Deleting a Chain
-
- Deleting a chain is simple as well.
-
-
-
- # ipchains -X test
- #
-
-
-
- Why `-X'? Well, all the good letters were taken.
-
-
- There are a couple of restrictions to deleting chains: they must be
- empty (see ``Flushing a Chain'' below) and they must not be the target
- of any rule. You can't delete any of the three built-in chains.
-
-
-
- 4.1.5.8. Flushing a Chain
-
- There is a simple way of emptying all rules out of a chain, using the
- `-F' command.
-
-
-
- # ipchains -F forward
- #
-
-
-
- If you don't specify a chain, then all chains will be flushed.
-
-
- 4.1.5.9. Listing a Chain
-
- You can list all the rules in a chain by using the `-L' command.
-
-
-
- # ipchains -L input
- Chain input (refcnt = 1): (policy ACCEPT)
- target prot opt source destination ports
- ACCEPT icmp ----- anywhere anywhere any
- # ipchains -L test
- Chain test (refcnt = 0):
- target prot opt source destination ports
- DENY icmp ----- localnet/24 anywhere any
- #
-
-
-
- The `refcnt' listed for test is the number of rules which have test as
- their target. This must be zero (and the chain be empty) before this
- chain can be deleted.
-
-
- If the chain name is omitted, all chains are listed, even empty ones.
-
-
- There are three options which can accompany `-L'. The `-n' (numeric)
- option is very useful as it prevents ipchains from trying to lookup
- the IP addresses, which (if you are using DNS like most people) will
- cause large delays if your DNS is not set up properly, or you have
- filtered out DNS requests. It also causes ports to be printed out as
- numbers rather than names.
-
-
- The `-v' options shows you all the details of the rules, such as the
- the packet and byte counters, the TOS masks, the interface, and the
- packet mark. Otherwise these values are omitted. For example:
-
-
-
- # ipchains -v -L input
- Chain input (refcnt = 1): (policy ACCEPT)
- pkts bytes target prot opt tosa tosx ifname mark source destination ports
- 10 840 ACCEPT icmp ----- 0xFF 0x00 lo anywhere anywhere any
-
-
-
- Note that the packet and byte counters are printed out using the
- suffixes `K', `M' or `G' for 1000, 1,000,000 and 1,000,000,000
- respectively. Using the `-x' (expand numbers) flag as well prints the
- full numbers, no matter how large they are.
-
-
- 4.1.5.10. Resetting (Zeroing) Counters
-
- It is useful to be able to reset the counters. This can be done with
- the `-Z' (zero counters) option. For example:
-
-
-
- # ipchains -v -L input
- Chain input (refcnt = 1): (policy ACCEPT)
- pkts bytes target prot opt tosa tosx ifname mark source destination ports
- 10 840 ACCEPT icmp ----- 0xFF 0x00 lo anywhere anywhere any
- # ipchains -Z input
- # ipchains -v -L input
- Chain input (refcnt = 1): (policy ACCEPT)
- pkts bytes target prot opt tosa tosx ifname mark source destination ports
- 0 0 ACCEPT icmp ----- 0xFF 0x00 lo anywhere anywhere any
- #
-
-
-
- The problem with this approach is that sometimes you need to know the
- counter values immediately before they are reset. In the above
- example, some packets could pass through between the `-L' and `-Z'
- commands. For this reason, you can use the `-L' and `-Z' together, to
- reset the counters while reading them. Unfortunately, if you do this,
- you can't operate on a single chain: you have to list and zero all the
- chains at once.
-
-
-
- # ipchains -L -v -Z
- Chain input (policy ACCEPT):
- pkts bytes target prot opt tosa tosx ifname mark source destination ports
- 10 840 ACCEPT icmp ----- 0xFF 0x00 lo anywhere anywhere any
-
- Chain forward (refcnt = 1): (policy ACCEPT)
- Chain output (refcnt = 1): (policy ACCEPT)
- Chain test (refcnt = 0):
- 0 0 DENY icmp ----- 0xFF 0x00 ppp0 localnet/24 anywhere any
- # ipchains -L -v
- Chain input (policy ACCEPT):
- pkts bytes target prot opt tosa tosx ifname mark source destination ports
- 10 840 ACCEPT icmp ----- 0xFF 0x00 lo anywhere anywhere any
-
- Chain forward (refcnt = 1): (policy ACCEPT)
- Chain output (refcnt = 1): (policy ACCEPT)
- Chain test (refcnt = 0):
- 0 0 DENY icmp ----- 0xFF 0x00 ppp0 localnet/24 anywhere any
- #
-
-
-
- 4.1.5.11. Setting Policy
-
- We glossed over what happens when a packet hits the end of a built-in
- chain when we discussed how a packet walks through chains in
- ``Specifying a Target'' above. In this case, the policy of the chain
- determines the fate of the packet. Only built-in chains (input,
- output and forward) have policies, because if a packet falls off the
- end of a user-defined chain, traversal resumes at the previous chain.
-
-
- The policy can be any of the first four special targets: ACCEPT, DENY,
- REJECT or MASQ. MASQ is only valid for the `forward' chain.
-
-
- It is also important to note that a RETURN target in a rule in one of
- the built-in chains is useful to explicitly target the chain policy
- when a packet matches a rule.
-
-
- 4.1.6. Operations on Masquerading
-
- There are several parameters you can tweak for IP Masquerading. They
- are bundled with ipchains because it's not worth writing a separate
- tool for them (although this will change).
-
-
- The IP Masquerading command is `-M', and it can be combined with `-L'
- to list currently masqueraded connections, or `-S' to set the
- masquerading parameters.
-
-
- The `-L' command can be accompanied by `-n' (show numbers instead of
- hostnames and port names) or `-v' (show deltas in sequence numbers for
- masqueraded connection, just in case you care).
-
-
- The `-S' command should be followed by three timeout values, each in
- seconds: for TCP sessions, for TCP sessions after a FIN packet, and
- for UDP packets. If you don't want to change one of these values,
- simply give a value of `0'.
-
-
- The default values are listed in
- `/usr/src/linux/include/net/ip_masq.h', currently 15 minutes, 2
- minutes and 5 minutes respectively.
-
-
- The most common value to change is the first one, for FTP (see ``FTP
- Nightmares'' below).
-
-
- Note the problems with setting timeouts listed in ``I can't set
- masquerading timeouts!''.
-
-
- 4.1.7. Checking a Packet
-
- Sometimes you want to see what happens when a certain packet enters
- your machine, such as for debugging your firewall chains. ipchains
- has the `-C' command to allow this, using the exact same routines that
- the kernel uses to diagnose real packets.
-
-
- You specify which chain to test the packet on by following the `-C'
- argument with its name. Whereas the kernel always starts traversing
- on the input, output or forward chains, you are allowed to begin
- traversing on any chain for testing purposes.
-
-
-
- The details of the `packet' are specified using the same syntax used
- to specify firewall rules. In particular, a protocol (`-p'), source
- address (`-s'), destination address (`-d') and interface (`-i') are
- compulsory. If the protocol is TCP or UDP, then a single source and a
- single destination port must be specified, and a ICMP type and code
- must be specified for the ICMP protocol (unless the `-f' flag is
- specified to indicate a fragment rule, in which case these options are
- illegal).
-
-
- If the protocol is TCP (and the `-f' flag is not specified), the `-y'
- flag may be specified, to indicate that the test packet should have
- the SYN bit set.
-
-
- Here is an example of testing a TCP SYN packet from 192.168.1.1 port
- 60000 to 192.168.1.2 port www, coming in the eth0 interface, entering
- the `input' chain. (This is a classic incoming WWW connection
- initiation):
-
-
-
- # ipchains -C input -p tcp -y -i eth0 -s 192.168.1.1 60000 -d 192.168.1.2 www
- packet accepted
- #
-
-
-
- 4.1.8. Multiple Rules at Once and Watching What Happens
-
- Sometimes a single command line can result in multiple rules being
- effected. This is done in two ways. Firstly, if you specify a
- hostname which resolves (using DNS) to multiple IP addresses, ipchains
- will act as if you had typed multiple commands with each combination
- of addresses.
-
-
- So if the hostname `www.foo.com' resolves to three IP addresses, and
- the hostname `www.bar.com' resolves to two IP addresses, then the
- command `ipchains -A input -j reject -s www.bar.com -d www.foo.com'
- would append six rules to the input chain.
-
-
- The other way to have ipchains perform multiple actions is to use the
- bidirectional flag (`-b'). This flag makes ipchains behave as if you
- had typed the command twice, the second time with the `-s' and `-d'
- arguments reversed. So, to avoid forwarding either to or from
- 192.168.1.1, you could do the following:
-
-
-
- # ipchains -b -A forward -j reject -s 192.168.1.1
- #
-
-
-
- Personally, I don't like the `-b' option much; if you want
- convenience, see ``Using ipchains-save'' below.
-
-
- The -b option can be used with the insert (`-I'), delete (`-D') (but
- not the variation which takes a rule number), append (`-A') and check
- (`-C') commands.
-
-
- Another useful flag is `-v' (verbose) which prints out exactly what
- ipchains is doing with your commands. This is useful if you are
- dealing with commands that may effect multiple rules. For example,
- here we check the behaviour of fragments between 192.168.1.1 and
- 192.168.1.2.
-
-
-
- # ipchains -v -b -C input -p tcp -f -s 192.168.1.1 -d 192.168.1.2 -i lo
- tcp opt ---f- tos 0xFF 0x00 via lo 192.168.1.1 -> 192.168.1.2 * -> *
- packet accepted
- tcp opt ---f- tos 0xFF 0x00 via lo 192.168.1.2 -> 192.168.1.1 * -> *
- packet accepted
- #
-
-
-
- 4.2. Useful Examples
-
- I have a dialup PPP connection (-i ppp0). I grab news (-p TCP -s
- news.virtual.net.au nntp) and mail (-p TCP -s mail.virtual.net.au
- pop-3) every time I dial up. I use Debian's FTP method to update my
- machine regularly (-p TCP -y -s ftp.debian.org.au ftp-data). I surf
- the web through my ISP's proxy while this is going on (-p TCP -d
- proxy.virtual.net.au 8080), but hate the ads from doubleclick.net on
- the Dilbert Archive (-p TCP -y -d 199.95.207.0/24 and -p TCP -y -d
- 199.95.208.0/24).
-
-
- I don't mind people trying to ftp to my machine while I'm online (-p
- TCP -d $LOCALIP ftp), but don't want anyone outside pretending to have
- an IP address of my internal network (-s 192.168.1.0/24). This is
- commonly called IP spoofing, and there is a better way to protect
- yourself from it in the 2.1.x kernels and above: see ``How do I set up
- IP spoof protection?''.
-
-
- This setup is fairly simple, because there are currently no other
- boxes on my internal network.
-
-
- I don't want any local process (ie. Netscape, lynx etc.) to connect to
- doubleclick.net:
-
-
-
- # ipchains -A output -d 199.95.207.0/24 -j REJECT
- # ipchains -A output -d 199.95.208.0/24 -j REJECT
- #
-
-
-
- Now I want to set priorities on various outgoing packets (there isn't
- much point in doing it on incoming packets). Since I have a fair
- number of these rules, it makes sense to put them all in a single
- chain, called ppp-out.
-
-
-
- # ipchains -N ppp-out
- # ipchains -A output -i ppp0 -j ppp-out
- #
-
-
-
- Minimum delay for web traffic & telnet.
-
-
-
- # ipchains -A ppp-out -p TCP -d proxy.virtual.net.au 8080 -t 0x01 0x10
- # ipchains -A ppp-out -p TCP -d 0.0.0.0/0 telnet -t 0x01 0x10
- #
-
-
-
- Low cost for ftp data, nntp, pop-3:
-
-
-
- # ipchains -A ppp-out -p TCP -d 0.0.0.0/0 ftp-data -t 0x01 0x02
- # ipchains -A ppp-out -p TCP -d 0.0.0.0/0 nntp -t 0x01 0x02
- # ipchains -A ppp-out -p TCP -d 0.0.0.0/0 pop-3 -t 0x01 0x02
- #
-
-
-
- There are a few restrictions on packets coming in the ppp0 interface:
- let's create a chain called `ppp-in':
-
-
-
- # ipchains -N ppp-in
- # ipchains -A input -i ppp0 -j ppp-in
- #
-
-
-
- Now, no packets coming in ppp0 should be claiming a source address of
- 192.168.1.*, so we log and deny them:
-
-
-
- # ipchains -A ppp-in -s 192.168.1.0/24 -l -j DENY
- #
-
-
-
- I allow UDP packets in for DNS (I run a caching nameserver which
- forwards all requests to 203.29.16.1, so I expect DNS replies from
- them only), incoming ftp, and return ftp-data only (which should only
- be going to a port above 1023, and not the X11 ports around 6000).
-
-
-
- # ipchains -A ppp-in -p UDP -s 203.29.16.1 -d $LOCALIP dns -j ACCEPT
- # ipchains -A ppp-in -p TCP -s 0.0.0.0/0 ftp-data -d $LOCALIP 1024:5999 -j ACCEPT
- # ipchains -A ppp-in -p TCP -s 0.0.0.0/0 ftp-data -d $LOCALIP 6010: -j ACCEPT
- # ipchains -A ppp-in -p TCP -d $LOCALIP ftp -j ACCEPT
- #
-
-
-
- I allow TCP reply packets back in
-
-
-
- # ipchains -A ppp-in -p TCP ! -y -j ACCEPT
- #
-
-
-
- Finally, local-to-local packets are OK:
-
-
-
- # ipchains -A input -i lo -j ACCEPT
- #
-
-
-
- Now, my default policy on the input chain is DENY, so everything else
- gets dropped:
-
-
-
- # ipchains -P input DENY
- #
-
-
-
- NOTE: I wouldn't set up my chains in this order, as packets might get
- through while I'm setting up. Safest is usually to set the policy to
- DENY first, then insert the rules. Of course, if your rules require
- DNS lookups to resolve hostnames, you could be in trouble.
-
-
- 4.2.1. Using ipchains-save
-
- Setting up firewall chains just the way you want them, and then trying
- to remember the commands you used so you can do them next time is a
- pain.
-
-
- So, ipchains-save is a script which reads your current chains setup
- and saves it to a file. For the moment I'll keep you in suspense with
- regards to what ipchains-restore does.
-
-
- ipchains-save can save a single chain, or all chains (if no chain name
- is specified). The only option currently permitted is `-v' which
- prints the rules (to stderr) as they are saved. The policy of the
- chain is also saved for input, output and forward chains.
- # ipchains-save > my_firewall
- Saving `input'.
- Saving `output'.
- Saving `forward'.
- Saving `ppp-in'.
- Saving `ppp-out'.
- #
-
-
-
- 4.2.2. Using ipchains-restore
-
- ipchains-restore restores chains as saved with ipchains-save. It can
- take two options: `-v' which describes each rule as it is added, and
- `-f' which forces flushing of user-defined chains if they exist, as
- described below.
-
-
- If a user-defined chain is found in the input, ipchains-restore checks
- if that chain already exists. If it does, then you will be prompted
- whether the chains should be flushed (cleared of all rules) or whether
- restoring this chain should be skipped. If you specified `-f' on the
- command line, you will not be prompted; the chain will be flushed.
-
-
- For example:
-
-
-
- # ipchains-restore < my_firewall
- Restoring `input'.
- Restoring `output'.
- Restoring `forward'.
- Restoring `ppp-in'.
- Chain `ppp-in' already exists. Skip or flush? [S/f]? s
- Skipping `ppp-in'.
- Restoring `ppp-out'.
- Chain `ppp-out' already exists. Skip or flush? [S/f]? f
- Flushing `ppp-out'.
- #
-
-
-
- 5. Miscellaneous.
-
- This section contains all the information and FAQs that I couldn't fit
- inside the structure above.
-
-
- 5.1. How to Organize Your Firewall Rules
-
- This question requires some thought. You can try to organize them to
- optimize speed (minimize the number of rule-checks for the most common
- packets) or to increase manageability.
-
-
- If you have an intermittent link, say a PPP link, you might want to
- set the first rule in the input chain to be set to `-i ppp0 -j DENY'
- at boot time, then have something like this in your ip-up script:
-
-
-
- # Re-create the `ppp-in' chain.
- ipchains-restore -f < ppp-in.firewall
-
- # Replace DENY rule with jump to ppp-handling chain.
- ipchains -R input 1 -i ppp0 -j ppp-in
-
-
-
- Your ip-down script would look like:
-
-
-
- ipchains -R input 1 -i ppp0 -j DENY
-
-
-
- 5.2. What Not To Filter Out
-
- There are some things you should be aware of before you start
- filtering out everything you don't want.
-
-
- 5.2.1. ICMP packets
-
- ICMP packets are used (among other things) to indicate failure for
- other protocols (such as TCP and UDP). `destination-unreachable'
- packets in particular. Blocking these packets means that you will
- never get `Host unreachable' or `No route to host' errors; any
- connections will just wait for a reply that never comes. This is
- irritating, but rarely fatal.
-
-
- A worse problem is the role of ICMP packets in MTU discovery. All
- good TCP implementations (Linux included) use MTU discovery to try to
- figure out what the largest packet that can get to a destination
- without being fragmented (fragmentation slows performance, especially
- when occasional fragments are lost). MTU discovery works by sending
- packets with the "Don't Fragment" bit set, and then sending smaller
- packets if it gets an ICMP packet indicating "Fragmentation needed but
- DF set" (`fragmentation-needed'). This is a type of `destination-
- unreachable' packet, and if it is never received, the local host will
- not reduce MTU, and performance will be abysmal or non-existent.
-
-
- Note that it is common to block all ICMP redirect messages (type 5);
- these can be used to manipulate routing (although good IP stacks have
- safeguards), and so are often seen as slightly risky.
-
-
- 5.2.2. TCP Connections to DNS (nameservers)
-
- If you're trying to block outgoing TCP connections, remember that DNS
- doesn't always use UDP; if the reply from the server exceeds 512
- bytes, the client uses a TCP connection (still going to port number
- 53) to get the data.
-
-
- This can be a trap because DNS will `mostly work' if you disallow such
- TCP transfers; you may experience strange long delays and other
- occasional DNS problems if you do.
-
- If your DNS queries are always directed at the same external source
- (either directly by using the nameserver line in /etc/resolv.conf or
- by using a caching nameserver in forward mode), then you need only
- allow TCP connections to port domain on that nameserver from the local
- domain port (if using a caching nameserver) or from a high port (>
- 1023) if using /etc/resolv.conf.
-
-
- 5.2.3. FTP Nightmares
-
- The classic packet filtering problem is FTP. FTP has two modes; the
- traditional one is called active mode and the more recent one is
- called passive mode. Web browsers usually default to passive mode,
- but command-line FTP programs usually default to active mode.
-
-
- In active mode, when the remote end wants to send a file (or even the
- results of an ls or dir command) it tries to open a TCP connection to
- the local machine. This means you can't filter out these TCP
- connections without breaking active FTP.
-
-
- If you have the option of using passive mode, then fine; passive mode
- makes data connections from client to server, even for incoming data.
- Otherwise, it is recommended that you only allow TCP connections to
- ports above 1024 and not between 6000 and 6010 (6000 is used for X-
- Windows).
-
-
- 5.3. Filtering out Ping of Death
-
- Linux boxes are now immune to the famous Ping of Death, which involves
- sending an illegally-large ICMP packet which overflows buffers in the
- TCP stack on the receiver and causes havoc.
-
-
- If you are protecting boxes which might be vulnerable, you could
- simply block ICMP fragments. Normal ICMP packets aren't large enough
- to require fragmentation, so you won't break anything except big
- pings. I have heard (unconfirmed) reports that some systems required
- only the last fragment of an oversize ICMP packet to corrupt them, so
- blocking only the first fragment is not recommended.
-
-
- While the exploit programs I have seen all use ICMP, there is no
- reasons that TCP or UDP fragments (or an unknown protocol) could not
- be used for this attack, so blocking ICMP fragments is only a
- temporary solution.
-
-
- 5.4. Filtering out Teardrop and Bonk
-
- Teardrop and Bonk are two attacks (mainly against Microsoft Windows NT
- machines) which rely on overlapping fragments. Having your Linux
- router do defragmentation, or disallowing all fragments to your
- vulnerable machines are the other options.
-
-
- 5.5. Filtering out Fragment Bombs
-
- Some less-reliable TCP stacks are said to have problems dealing with
- large numbers of fragments of packets when they don't receive all the
- fragments. Linux does not have this problem. You can filter out
- fragments (which might break legitimate uses) or compile your kernel
- with `IP: always defragment' set to `Y' (only if your Linux box is the
- only possible route for these packets).
- 5.6. Changing Firewall Rules
-
- There are some timing issues involved in altering firewall rules. If
- you are not careful, you can let packets through while you are half-
- way through your changes. A simplistic approach is to do the
- following:
-
-
-
- # ipchains -I input 1 -j DENY
- # ipchains -I output 1 -j DENY
- # ipchains -I forward 1 -j DENY
-
- ... make changes ...
-
- # ipchains -D input 1
- # ipchains -D output 1
- # ipchains -D forward 1
- #
-
-
-
- This drops all packets for the duration of the changes.
-
-
- If your changes are restricted to a single chain, you might want to
- create a new chain with the new rules, and then replace (`-R') the
- rule that pointed to the old chain with one that points to the new
- chain: then you can delete the old chain. This replacement will occur
- atomically.
-
-
- 5.7. How Do I Set Up IP Spoof Protection?
-
- IP spoofing is a technique where a host sends out packets which claim
- to be from another host. Since packet filtering makes decisions based
- on this source address, IP spoofing is uses to fool packet filters.
- It is also used to hide the identity of attackers using SYN attacks,
- Teardrop, Ping of Death and the like (don't worry if you don't know
- what they are).
-
-
- The best way to protect from IP spoofing is called Source Address
- Verification, and it is done by the routing code, and not firewalling
- at all. Look for a file called /proc/sys/net/ipv4/conf/all/rp_filter.
- If this exists, then turning on Source Address Verification at every
- boot is the right solution for you. To do that, insert the following
- lines somewhere in your init scripts, before any network interfaces
- are initialized:
-
-
-
- # This is the best method: turn on Source Address Verification and get
- # spoof protection on all current and future interfaces.
- if [ -e /proc/sys/net/ipv4/conf/all/rp_filter ]; then
- echo -n "Setting up IP spoofing protection..."
- for f in /proc/sys/net/ipv4/conf/*/rp_filter; do
- echo 1 > $f
- done
- echo "done."
- else
- echo PROBLEMS SETTING UP IP SPOOFING PROTECTION. BE WORRIED.
- echo "CONTROL-D will exit from this shell and continue system startup."
- echo
- # Start a single user shell on the console
- /sbin/sulogin $CONSOLE
- fi
-
-
-
- If you cannot do this, you can manually insert rules to protect every
- interface. This requires knowledge of each interface. The 2.1
- kernels automatically reject packets claiming to come from the 127.*
- addresses (reserved for the local loopback interface, lo).
-
-
- For example, say we have three interfaces, eth0, eth1 and ppp0. We
- can use ifconfig to tell us the address and netmask of the interfaces.
- Say eth0 was attached to a network 192.168.1.0 with netmask
- 255.255.255.0, eth1 was attached to a network 10.0.0.0 with netmask
- 255.0.0.0, and ppp0 connected to the Internet (where any address
- except the reserved private IP addresses are allowed), we would insert
- the following rules:
-
-
-
- # ipchains -A input -i eth0 -s ! 192.168.1.0/255.255.255.0 -j DENY
- # ipchains -A input -i ! eth0 -s 192.168.1.0/255.255.255.0 -j DENY
- # ipchains -A input -i eth1 -s ! 10.0.0.0/255.0.0.0 -j DENY
- # ipchains -A input -i ! eth1 -s 10.0.0.0/255.0.0.0 -j DENY
- #
-
-
-
- This approach is not as good as the Source Address Verification
- approach, because if your network changes, you have to change your
- firewalling rules to keep up.
-
-
- If you are running a 2.0 series kernel, you might want to protect the
- loopback interface as well, using a rule like this:
-
-
-
- # ipchains -A input -i ! lo -s 127.0.0.0/255.0.0.0 -j DENY
- #
-
-
-
- 5.8. Advanced Projects
-
- There is a userspace library I have written which is included with the
- source distribution called `libfw'. It uses the ability of IP Chains
- 1.3 and above to copy a packet to userspace (using the
- IP_FIREWALL_NETLINK config option).
-
-
- The mark value can be used to specify the Quality of Service
- parameters for packets, or to specify how packets should be port-
- forwarded. I've never used either, but if you want to write about it,
- please contact me.
-
-
- Things such as stateful inspection (I prefer the term dynamic
- firewalling) can be implemented in userspace using this library.
- Other nifty ideas include controlling packets on a per-user basis by
- doing a lookup in a userspace daemon. This should be pretty easy.
-
-
- 5.8.1. SPF: Stateful Packet Filtering
-
- ftp://ftp.interlinx.bc.ca/pub/spf
- is the site of Brian Murrell's SPF project, which does connection
- tracking in userspace. It adds significant security for low-bandwidth
- sites.
-
-
- There's little documentation at present, but here's a post to the
- mailing list in which Brian answered some questions:
-
-
-
- > I believe it does exactly what I want: Installing a temporary
- > "backward"-rule to let packets in as a response to an
- > outgoing request.
-
- Yup, that is exactly what it does. The more protocols it
- understands, the more "backward" rules it gets right. Right
- now it has support for (from memory, please excuse any errors
- or omissions) FTP (both active and passive, in and out), some
- RealAudio, traceroute, ICMP and basic ICQ (inbound from the ICQ
- servers, and direct TCP connections, but alas the secondary
- direct TCP connections for things like file transfer, etc. are
- not there yet)
-
- > Is it a replacement for ipchains or a supplement?
-
- It is a supplement. Think of ipchains as the engine to allow
- and prevent packets from travelling across a Linux box. SPF is
- the driver, constantly monitoring traffic and telling ipchains
- how to change it's policies to reflect the changes in traffic
- patterns.
-
-
-
- 5.8.2. Michael Hasenstein's ftp-data hack
-
- Michael Hasenstein of SuSE has written a kernel patch which adds ftp
- connection tracking to ipchains. It can currently be found at
- http://www.suse.de/~mha/patch.ftp-data-2.gz
-
-
- 5.9. Future Enhancements
-
- Firewalling and NAT have being redesigned for 2.4. Plans and
- discussions are available on the netfilter list (see
- http://lists.samba.org ). These enhancements
- should clear up many outstanding usability issues (really, firewalling
- and masquerading shouldn't be this hard), and allow growth for far
- more flexible firewalling.
-
-
- 6. Common Problems
-
-
- 6.1. ipchains -L Freezes!
-
- You're probably blocking DNS lookups; it will eventually time out.
- Try using the `-n' (numeric) flag to ipchains, which suppresses the
- lookup of names.
-
-
-
- 6.2. Inverse doesn't work!
-
- You must put the `!' option by itself, with spaces either side. A
- classic mistake (warned about in 1.3.10) is:
-
-
-
- # ipchains -A input -i !eth0 -j DENY
- #
-
-
-
- There will never be an interface called `!eth0', but ipchains doesn't
- know that.
-
-
-
- 6.3. Masquerading/Forwarding Doesn't Work!
-
- Make sure that packet forwarding is enabled (in recent kernels it is
- disabled by default, meaning that packets never even try to traverse
- the `forward' chain). You can override this (as root) by typing
-
-
-
- # echo 1 > /proc/sys/net/ipv4/ip_forward
- #
-
-
-
- If this works for you, you can put this somewhere in your bootup
- scripts so it is enabled every time; you'll want to set up your
- firewalling before this command runs though, otherwise there's an
- opportunity for packets to slip through.
-
-
-
- 6.4. -j REDIR doesn't work!
-
- You must allow forwarding packets (see above) for redirect to work;
- otherwise the routing code drops the packet. So if you are just using
- redirect, and don't have any forwarding at all, you should be aware of
- that.
-
-
- Note that REDIR (being in the input chain) doesn't effect connections
- from a local process.
-
-
- 6.5. Wildcard Interfaces Don't Work!
-
- There was a bug in versions 2.1.102 and 2.1.103 of the kernel (and
- some old patches I produced) which made ipchains commands which
- specified a wildcard interface (such as -i ppp+) fail.
-
-
- This is fixed in recent kernels, and in the 2.0.34 patch on the web
- site. You can also fix it by hand in the kernel source by changing
- line 63 or so in include/linux/ip_fw.h:
-
-
-
- #define IP_FW_F_MASK 0x002F /* All possible flag bits mask */
-
-
-
- This should read ``0x003F''. Fix this and recompile the kernel.
-
-
- 6.6. TOS Doesn't Work!
-
- This was my mistake: setting the Type of Service field did not
- actually set the Type of Service in kernel versions 2.1.102 through
- 2.1.111. This problem was fixed in 2.1.112.
-
-
- 6.7. ipautofw and ipportfw Don't Work!
-
- For 2.0.x, this is true; I haven't time to create and maintain a jumbo
- patch for ipchains and ipautofw/ipportfw.
-
-
- For 2.1.x, download Juan Ciarlante's ipmasqadm from
-
-
-
-
- and use it exactly as you would have used ipautofw or ipportfw, except
- instead of ipportfw you type ipmasqadm portfw, and instead of ipautofw
- you type ipmasqadm autofw.
-
-
- 6.8. xosview is Broken!
-
- Upgrade to version 1.6.0 or above, which doesn't require any firewall
- rules at all for 2.1.x kernels. This seems to have broken again in
- the 1.6.1 release; please bug the author (it's not my fault!).
-
-
- 6.9. Segmentation Fault With `-j REDIRECT'!
-
- This was a bug in ipchains version 1.3.3. Please upgrade.
-
-
-
- 6.10. I Can't Set Masquerading Timeouts!
-
- True (for 2.1.x kernels) up to 2.1.123. In 2.1.124, trying to set the
- masquerading timeouts causes a kernel lockup (change return to ret =
- on line 1328 of net/ipv4/ip_fw.c). In 2.1.125, it works fine.
-
-
- 6.11. I Want to Firewall IPX!
-
- So do a number of others, it seems. My code only covers IP,
- unfortunately. On the good side, all the hooks are there to firewall
- IPX! You just need to write the code; I will happily help where
- possible.
-
-
- 7. A Serious Example.
-
- This example was extracted from Michael Neuling and my March 1999
- LinuxWorld Tutorial; this is not the only way to solve the given
- problem, but it is probably the simplest. I hope you will find it
- informative.
-
-
-
- 7.1. The Arrangement
-
-
- · Masqueraded internal network (various operating systems), which we
- call "GOOD".
-
- · Exposed servers in a separate network (called "DMZ" for
- Demilitarized Zone).
-
- · PPP Connection to the Internet (called "BAD").
-
-
-
- External Network (BAD)
- |
- |
- ppp0|
- ---------------
- | 192.84.219.1| Server Network (DMZ)
- | |eth0
- | |----------------------------------------------
- | |192.84.219.250 | | |
- | | | | |
- |192.168.1.250| | | |
- --------------- -------- ------- -------
- | eth1 | SMTP | | DNS | | WWW |
- | -------- ------- -------
- | 192.84.219.128 192.84.219.129 192.84.218.130
- |
- Internal Network (GOOD)
-
-
-
- 7.2. Goals
-
-
- Packet Filter box:
-
-
- PING any network
- This is really useful to tell if a machine is down.
-
-
- TRACEROUTE any network
- Once again, useful for diagnosis.
-
-
- Access DNS
- To make ping and DNS more useful.
-
-
-
- Within the DMZ:
-
-
- Mail server
-
- · SMTP to external
-
- · Accept SMTP from internal and external
-
- · Accept POP-3 from internal
-
- Name Server
-
- · Send DNS to external
-
- · Accept DNS from internal, external and packet filter box
-
-
- Web server
-
- · Accept HTTP from internal and external
-
- · Rsync access from internal
-
-
- Internal:
-
- Allow WWW, ftp, traceroute, ssh to external
- These are fairly standard things to allow: some places start by
- allowing the internal machines to do just about everything, but
- here we're being restrictive.
-
-
- Allow SMTP to Mail server
- Obviously, we want them to be able to send mail out.
-
-
- Allow POP-3 to Mail server
- This is how they read their mail.
-
-
- Allow DNS to Name server
- They need to be able to look up external names for WWW, ftp,
- traceroute and ssh.
-
-
- Allow rsync to Web server
- This is how they synchronize the external web server with the
- internal one.
-
-
- Allow WWW to Web server
- Obviously, they should be able to connect to our external web
- server.
-
-
- Allow ping to packet filter box
- This is a courteous thing to allow: it means that they can test
- if the firewall box is down (so we don't get blamed if an
- external site is broken).
-
-
-
- 7.3. Before Packet Filtering
-
-
- · Anti-spoofing
-
-
- Since we don't have any asymmetric routing, we can simply turn on
- anti-spoofing for all interfaces.
-
-
-
- # for f in /proc/sys/net/ipv4/conf/*/rp_filter; do echo 1 > $f; done
- #
-
-
-
- · Set filtering rules to DENY all:
-
-
- We still allow local loopback traffic, but deny anything else.
-
-
-
- # ipchains -A input -i ! lo -j DENY
- # ipchains -A output -i ! lo -j DENY
- # ipchains -A forward -j DENY
- #
-
-
-
- · Set Up Interfaces
-
-
- This is usually done in the boot scripts. Make sure the above
- steps are done before the interfaces are configured, to prevent
- packet leakage before the rules are set up.
-
-
- · Insert per-protocol masquerading modules.
-
- We need to insert the masquerading module for FTP, so that active
- and passive FTP `just work' from the internal network.
-
-
-
- # insmod ip_masq_ftp
- #
-
-
- 7.4. Packet Filtering for Through Packets
-
- With masquerading, it's best to filter in the forward chain.
-
-
- Split forward chain into various user chains depending on source/dest
- interfaces; this breaks the problem down into managable chunks.
-
-
-
- ipchains -N good-dmz
- ipchains -N bad-dmz
- ipchains -N good-bad
- ipchains -N dmz-good
- ipchains -N dmz-bad
- ipchains -N bad-good
-
-
-
- ACCEPTing standard error ICMPs is a common thing to do, so we create a
- chain for it.
-
-
-
- ipchains -N icmp-acc
-
-
-
- 7.4.1. Set Up Jumps From forward Chain
-
- Unfortunately, we only know (in the forward chain) the outgoing
- interface. Thus, to figure out what interface the packet came in on,
- we use the source address (the anti-spoofing prevents address faking).
-
-
- Note that we log anything which doesn't match any of these (obviously,
- this should never happen).
-
-
-
- ipchains -A forward -s 192.168.1.0/24 -i eth0 -j good-dmz
- ipchains -A forward -s 192.168.1.0/24 -i ppp0 -j good-bad
- ipchains -A forward -s 192.84.219.0/24 -i ppp0 -j dmz-bad
- ipchains -A forward -s 192.84.219.0/24 -i eth1 -j dmz-good
- ipchains -A forward -i eth0 -j bad-dmz
- ipchains -A forward -i eth1 -j bad-good
- ipchains -A forward -j DENY -l
-
-
-
- 7.4.2. Define the icmp-acc Chain
-
- Packets which are one of the error ICMPs get ACCEPTed, otherwise,
- control will pass back to the calling chain.
-
-
-
- ipchains -A icmp-acc -p icmp --icmp-type destination-unreachable -j ACCEPT
- ipchains -A icmp-acc -p icmp --icmp-type source-quench -j ACCEPT
- ipchains -A icmp-acc -p icmp --icmp-type time-exceeded -j ACCEPT
- ipchains -A icmp-acc -p icmp --icmp-type parameter-problem -j ACCEPT
-
-
-
- 7.4.3. Good (Internal) to DMZ (Servers)
-
- Internal restrictions:
-
- · Allow WWW, ftp, traceroute, ssh to external
-
- · Allow SMTP to Mail server
-
- · Allow POP-3 to Mail server
-
- · Allow DNS to Name server
-
- · Allow rsync to Web server
-
- · Allow WWW to Web server
-
- · Allow ping to packet filter box
-
- Could do masquerading from internal network into DMZ, but here we
- don't. Since noone in the internal network should be trying to do
- evil things, we log any packets that get denied.
-
-
- Note that old versions of Debian called `pop3' `pop-3' in
- /etc/services, which disagrees with RFC1700.
-
-
-
- ipchains -A good-dmz -p tcp -d 192.84.219.128 smtp -j ACCEPT
- ipchains -A good-dmz -p tcp -d 192.84.219.128 pop3 -j ACCEPT
- ipchains -A good-dmz -p udp -d 192.84.219.129 domain -j ACCEPT
- ipchains -A good-dmz -p tcp -d 192.84.219.129 domain -j ACCEPT
- ipchains -A good-dmz -p tcp -d 192.84.218.130 www -j ACCEPT
- ipchains -A good-dmz -p tcp -d 192.84.218.130 rsync -j ACCEPT
- ipchains -A good-dmz -p icmp -j icmp-acc
- ipchains -A good-dmz -j DENY -l
-
-
-
- 7.4.4. Bad (external) to DMZ (servers).
-
-
-
- · DMZ restrictions:
-
- · Mail server
-
- · SMTP to external
-
- · Accept SMTP from internal and external
-
- · Accept POP-3 from internal
-
-
- · Name server
-
- · Send DNS to external
-
- · Accept DNS from internal, external and packet filter box
-
-
- · Web server
-
- · Accept HTTP from internal and external
-
- · Rsync access from internal
-
-
- · Things we allow from external network to DMZ.
-
- · Don't log violations, as they may happen.
-
-
-
- ipchains -A bad-dmz -p tcp -d 192.84.219.128 smtp -j ACCEPT
- ipchains -A bad-dmz -p udp -d 192.84.219.129 domain -j ACCEPT
- ipchains -A bad-dmz -p tcp -d 192.84.219.129 domain -j ACCEPT
- ipchains -A bad-dmz -p tcp -d 192.84.218.130 www -j ACCEPT
- ipchains -A bad-dmz -p icmp -j icmp-acc
- ipchains -A bad-dmz -j DENY
-
-
-
- 7.4.5. Good (internal) to Bad (external).
-
-
- · Internal restrictions:
-
- · Allow WWW, ftp, traceroute, ssh to external
-
- · Allow SMTP to Mail server
-
- · Allow POP-3 to Mail server
-
- · Allow DNS to Name server
-
- · Allow rsync to Web server
-
- · Allow WWW to Web server
-
- · Allow ping to packet filter box
-
- · Many people allow everything from the internal to external
- networks, then add restrictions. We're being fascist.
-
- · Log violations.
-
- · Passive FTP handled by masq. module.
-
- · UDP destination ports 33434 and up are used by traceroute.
-
-
-
- ipchains -A good-bad -p tcp --dport www -j MASQ
- ipchains -A good-bad -p tcp --dport ssh -j MASQ
- ipchains -A good-bad -p udp --dport 33434:33500 -j MASQ
- ipchains -A good-bad -p tcp --dport ftp -j MASQ
- ipchains -A good-bad -p icmp --icmp-type ping -j MASQ
- ipchains -A good-bad -j REJECT -l
-
-
-
- 7.4.6. DMZ to Good (internal).
-
-
-
- · Internal restrictions:
-
- · Allow WWW, ftp, traceroute, ssh to external
-
- · Allow SMTP to Mail server
-
- · Allow POP-3 to Mail server
-
- · Allow DNS to Name server
-
- · Allow rsync to Web server
-
- · Allow WWW to Web server
-
- · Allow ping to packet filter box
-
-
- · If we were masquerading from the internal network to the DMZ,
- simply refuse any packets coming the other way. As it is, only
- allow packets which might be part of an established connection.
-
-
-
- ipchains -A dmz-good -p tcp ! -y -s 192.84.219.128 smtp -j ACCEPT
- ipchains -A dmz-good -p udp -s 192.84.219.129 domain -j ACCEPT
- ipchains -A dmz-good -p tcp ! -y -s 192.84.219.129 domain -j ACCEPT
- ipchains -A dmz-good -p tcp ! -y -s 192.84.218.130 www -j ACCEPT
- ipchains -A dmz-good -p tcp ! -y -s 192.84.218.130 rsync -j ACCEPT
- ipchains -A dmz-good -p icmp -j icmp-acc
- ipchains -A dmz-good -j DENY -l
-
-
-
- 7.4.7. DMZ to bad (external).
-
-
-
- · DMZ restrictions:
-
- · Mail server
-
- · SMTP to external
-
- · Accept SMTP from internal and external
-
- · Accept POP-3 from internal
-
-
-
- · Name server
-
- · Send DNS to external
-
- · Accept DNS from internal, external and packet filter box
-
-
- · Web server
-
- · Accept HTTP from internal and external
-
- · Rsync access from internal
-
-
- ·
-
-
- ipchains -A dmz-bad -p tcp -s 192.84.219.128 smtp -j ACCEPT
- ipchains -A dmz-bad -p udp -s 192.84.219.129 domain -j ACCEPT
- ipchains -A dmz-bad -p tcp -s 192.84.219.129 domain -j ACCEPT
- ipchains -A dmz-bad -p tcp ! -y -s 192.84.218.130 www -j ACCEPT
- ipchains -A dmz-bad -p icmp -j icmp-acc
- ipchains -A dmz-bad -j DENY -l
-
-
-
- 7.4.8. Bad (external) to Good (internal).
-
-
-
- · We don't allow anything (non-masqueraded) from the external network
- to the internal network
-
-
- ipchains -A bad-good -j REJECT
-
-
-
- 7.4.9. Packet Filtering for the Linux Box Itself
-
-
-
- · If we want to use packet filtering on packets coming into the box
- itself, we need to do filtering in the input chain. We create one
- chain for each destination interface:
-
-
- ipchains -N bad-if
- ipchains -N dmz-if
- ipchains -N good-if
-
-
-
- · Create jumps to them:
-
-
-
- ipchains -A input -d 192.84.219.1 -j bad-if
- ipchains -A input -d 192.84.219.250 -j dmz-if
- ipchains -A input -d 192.168.1.250 -j good-if
-
-
-
- 7.4.9.1. Bad (external) interface.
-
-
-
- · Packet Filter box:
-
- · PING any network
-
- · TRACEROUTE any network
-
- · Access DNS
-
-
- · External interface also receives replies to masqueraded packets
- (masquerading uses source ports 61000 to 65095) and ICMP errors for
- them and PING replies.
-
-
-
- ipchains -A bad-if -i ! ppp0 -j DENY -l
- ipchains -A bad-if -p TCP --dport 61000:65095 -j ACCEPT
- ipchains -A bad-if -p UDP --dport 61000:65095 -j ACCEPT
- ipchains -A bad-if -p ICMP --icmp-type pong -j ACCEPT
- ipchains -A bad-if -j icmp-acc
- ipchains -A bad-if -j DENY
-
-
-
- 7.4.9.2. DMZ interface.
-
-
-
- · Packet Filter box restrictions:
-
- · PING any network
-
- · TRACEROUTE any network
-
- · Access DNS
-
-
- · DMZ interface receives DNS replies, ping replies and ICMP errors.
-
-
-
- ipchains -A dmz-if -i ! eth0 -j DENY
- ipchains -A dmz-if -p TCP ! -y -s 192.84.219.129 53 -j ACCEPT
- ipchains -A dmz-if -p UDP -s 192.84.219.129 53 -j ACCEPT
- ipchains -A dmz-if -p ICMP --icmp-type pong -j ACCEPT
- ipchains -A dmz-if -j icmp-acc
- ipchains -A dmz-if -j DENY -l
-
-
-
- 7.4.9.3. Good (internal) interface.
-
-
-
- · Packet Filter box restrictions:
-
- · PING any network
-
- · TRACEROUTE any network
-
- · Access DNS
-
-
- · Internal restrictions:
-
- · Allow WWW, ftp, traceroute, ssh to external
-
- · Allow SMTP to Mail server
-
- · Allow POP-3 to Mail server
-
- · Allow DNS to Name server
-
- · Allow rsync to Web server
-
- · Allow WWW to Web server
-
- · Allow ping to packet filter box
-
-
- · Internal interface receives pings, ping replies and ICMP errors.
-
-
-
- ipchains -A good-if -i ! eth1 -j DENY
- ipchains -A good-if -p ICMP --icmp-type ping -j ACCEPT
- ipchains -A good-if -p ICMP --icmp-type pong -j ACCEPT
- ipchains -A good-if -j icmp-acc
- ipchains -A good-if -j DENY -l
-
-
-
- 7.5. Finally
-
-
- · Delete blocking rules:
-
-
- ipchains -D input 1
- ipchains -D forward 1
- ipchains -D output 1
-
-
-
- 8. Appendix: Differences between ipchains and ipfwadm.
-
- Some of these changes are a result of kernel changes, and some a
- result of ipchains being different from ipfwadm.
-
-
-
- 1. Many arguments have been remapped: capitals now indicates a
- command, and lower case now indicates an option.
-
- 2. Arbitrary chains are supported, so even built-in chains have full
- names instead of flags (eg. `input' instead of `-I').
-
- 3. The `-k' option has vanished: use `! -y'.
-
- 4. The `-b' option actually inserts/appends/deletes two rules, rather
- than a single `bidirectional' rule.
-
- 5. The `-b' option can be passed to `-C' to do two checks (one in each
- direction).
-
- 6. The `-x' option to `-l' has been replaced by `-v'.
-
- 7. Multiple source and destination ports are not supported anymore.
- Hopefully being able to negate the port range will somewhat make up
- for that.
-
- 8. Interfaces can only be specified by name (not address). The old
- semantics got silently changed in the 2.1 kernel series anyway.
-
- 9. Fragments are examined, not automatically allowed through.
-
- 10.
- Explicit accounting chains have been done away with.
-
- 11.
- Arbitrary protocols over IP can be tested for.
-
- 12.
- The old behavior of SYN and ACK matching (which was previously
- ignored for non-TCP packets) has changed; the SYN option is not
- valid for non-TCP-specific rules.
-
- 13.
- Counters are now 64-bit on 32-bit machines, not 32-bit.
-
- 14.
- Inverse options are now supported.
-
- 15.
- ICMP codes are now supported.
-
- 16.
- Wildcard interfaces are now supported.
-
- 17.
- TOS manipulations are now sanity-checked: the old kernel code would
- silently stop you from (illegally) manipulating the `Must Be Zero'
- TOS bit; ipchains now returns an error if you try, as well as for
- other illegal cases.
-
-
- 8.1. Quick-Reference table.
-
- [ Mainly, command arguments are UPPER CASE, and option arguments are
- lower case ]
-
-
- One thing to note, masquerading is specified by `-j MASQ'; it is
- completely different from `-j ACCEPT', and not treated as merely a
- side-effect, unlike ipfwadm does.
-
-
- ================================================================
- | ipfwadm | ipchains | Notes
- ----------------------------------------------------------------
- | -A [both] | -N acct | Create an `acct' chain
- | |& -I 1 input -j acct | and have output and input
- | |& -I 1 output -j acct | packets traverse it.
- | |& acct |
- ----------------------------------------------------------------
- | -A in | input | A rule with no target
- ----------------------------------------------------------------
- | -A out | output | A rule with no target
- ----------------------------------------------------------------
- | -F | forward | Use this as [chain].
- ----------------------------------------------------------------
- | -I | input | Use this as [chain].
- ----------------------------------------------------------------
- | -O | output | Use this as [chain].
- ----------------------------------------------------------------
- | -M -l | -M -L |
- ----------------------------------------------------------------
- | -M -s | -M -S |
- ----------------------------------------------------------------
- | -a policy | -A [chain] -j POLICY | (but see -r and -m).
- ----------------------------------------------------------------
- | -d policy | -D [chain] -j POLICY | (but see -r and -m).
- ----------------------------------------------------------------
- | -i policy | -I 1 [chain] -j POLICY| (but see -r and -m).
- ----------------------------------------------------------------
- | -l | -L |
- ----------------------------------------------------------------
- | -z | -Z |
- ----------------------------------------------------------------
- | -f | -F |
- ----------------------------------------------------------------
- | -p | -P |
- ----------------------------------------------------------------
- | -c | -C |
- ----------------------------------------------------------------
- | -P | -p |
- ----------------------------------------------------------------
- | -S | -s | Only takes one port or
- | | | range, not multiples.
- ----------------------------------------------------------------
- | -D | -d | Only takes one port or
- | | | range, not multiples.
- ----------------------------------------------------------------
- | -V | | Use -i [name].
- ----------------------------------------------------------------
- | -W | -i |
- ----------------------------------------------------------------
- | -b | -b | Now actually makes 2 rules.
- ----------------------------------------------------------------
- | -e | -v |
- ----------------------------------------------------------------
- | -k | ! -y | Doesn't work unless
- | | | -p tcp also specified.
- ----------------------------------------------------------------
- | -m | -j MASQ |
- ----------------------------------------------------------------
- | -n | -n |
- ----------------------------------------------------------------
- | -o | -l |
- ----------------------------------------------------------------
- | -r [redirpt] | -j REDIRECT [redirpt] |
- ----------------------------------------------------------------
- | -t | -t |
- ----------------------------------------------------------------
- | -v | -v |
- ----------------------------------------------------------------
- | -x | -x |
- ----------------------------------------------------------------
- | -y | -y | Doesn't work unless
- | | | -p tcp also specified.
- ----------------------------------------------------------------
-
-
-
- 8.2. Examples of translated ipfwadm commands
-
- Old command: ipfwadm -F -p deny
-
- New command: ipchains -P forward DENY
-
-
- Old command: ipfwadm -F -a m -S 192.168.0.0/24 -D 0.0.0.0/0
-
- New command: ipchains -A forward -j MASQ -s 192.168.0.0/24 -d
- 0.0.0.0/0
-
-
- Old command: ipfwadm -I -a accept -V 10.1.2.1 -S 10.0.0.0/8 -D
- 0.0.0.0/0
-
- New command: ipchains -A input -j ACCEPT -i eth0 -s 10.0.0.0/8 -d
- 0.0.0.0/0
-
- (Note that there is no equivalent for specifying interfaces by
- address: use the interface name. On this machine, 10.1.2.1
- corresponds to eth0).
-
-
- 9. Appendix: Using the ipfwadm-wrapper script.
-
- The ipfwadm-wrapper shell script should be a plug-in replacement of
- ipfwadm for backwards compatibility with ipfwadm 2.3a.
-
-
- The only feature it can't really handle is the `-V' option. When this
- is used, a warning is given. If the `-W' option is also used, the
- `-V' option is ignored. Otherwise, the script tries to find the
- interface name associated with that address, using ifconfig. If that
- fails (such as for an interface which is down) then it will exit with
- an error message.
-
-
- This warning can be suppressed by either changing the `-V' to a `-W',
- or directing the standard output of the script to /dev/null.
-
-
- If you should find any mistakes in this script, or any changes between
- the real ipfwadm and this script, please report a bug to me: send an
- EMail to rusty@linuxcare.com with "BUG-REPORT" in the subject. Please
- list your old version of ipfwadm (ipfwadm -h), your version of
- ipchains (ipchains --version), the version of the ipfwadm wrapper
- script (ipfwadm-wrapper --version). Also send the output of ipchains-
- save. Thanks in advance.
-
-
- Mix ipchains with this ipfwadm-wrapper script at your own peril.
-
-
- 10. Appendix: Thanks.
-
- Many thanks have to go to Michael Neuling, who wrote the first
- releasable cut of the IP chains code while working for me. Public
- apologies for nixing his result-caching idea, which Alan Cox later
- proposed and I have finally begun implementing, having seen the error
- of my ways.
-
-
- Thanks to Alan Cox for his 24-hour EMail tech support, and
- encouragement.
-
-
- Thanks to all the authors of the ipfw and ipfwadm code, especially Jos
- Vos. Standing on the shoulders of giants and all that... This
- applies to Linus Torvalds and all the kernel and userspace hackers as
- well.
-
-
- Thanks to the diligent beta testers and bughunters, especially Jordan
- Mendelson, Shaw Carruthers, Kevin Moule, Dr. Liviu Daia, Helmut Adams,
- Franck Sicard, Kevin Littlejohn, Matt Kemner, John D. Hardin, Alexey
- Kuznetsov, Leos Bitto, Jim Kunzman, Gerard Gerritsen, Serge Sivkov,
- Andrew Burgess, Steve Schmidtke, Richard Offer, Bernhard Weisshuhn,
- Larry Auton, Ambrose Li, Pavel Krauz, Steve Chadsey, Francesco
- Potorti`, Alain Knaff, Casper Boden-Cummins and Henry Hollenberg.
-
-
- 10.1. Translations
-
- People who do translations should put themselves at the top of the
- Thanks page, like so: `Special thanks to XXX, for translating
- everything exactly from my English.'. Then tell me about your
- translation so I can include it here.
-
-
- Arnaud Launay, asl@launay.org:
- http://www.freenix.fr/unix/linux/HOWTO/IPCHAINS-HOWTO.html
-
-
-
- Giovanni Bortolozzo, borto@pluto.linux.it:
- http://www.pluto.linux.it/ildp/HOWTO/IPCHAINS-HOWTO.html
-
-
-
- Herman Rodríguez, herman@maristas.dhis.org:
- http://netfilter.kernelnotes.org/ipchains/spanish/HOWTO.html
-
-
-
-Linux IP Masquerade HOWTO
-
-David A. Ranch
-
-
-
-v2.00.110903, 2003-11-09
-
-
-This document describes how to enable the Linux IP Masquerade feature on a
-given Linux host. IP Masquerade is a form of Network Address Translation or
-NAT which NAT allows internally connected computers that do not have one or
-more registered Internet IP addresses to communicate to the Internet via the
-Linux server's Internet IP address.
-
------------------------------------------------------------------------------
-Table of Contents
-1. Introduction
- 1.1. Introduction to IP Masquerading or IP MASQ
- 1.2. Foreword, Feedback & Credits
- 1.3. Copyright & Disclaimer
-
-
-2. Background Knowledge
- 2.1. What is IP Masquerade?
- 2.2. Current Status
- 2.3. Who Can Benefit From IP Masquerade?
- 2.4. Who Doesn't Need IP Masquerade?
- 2.5. How does IP Masquerade Work?
- 2.6. Requirements for IP Masquerade on Linux 2.4.x
- 2.7. Requirements for IP Masquerade on Linux 2.2.x
- 2.8. Requirements for IP Masquerade on Linux 2.0.x
-
-
-3. Setting Up IP Masquerade
- 3.1. Compiling a new kernel if needed
- 3.2. Checking your existing kernel for MASQ functionality
- 3.2.1. Compiling Linux 2.4.x Kernels
- 3.2.2. Compiling Linux 2.2.x Kernels
- 3.2.3. Compiling Linux 2.0.x Kernels
-
-
- 3.3. Assigning Private Network IP Addresses to the Internal LAN
- 3.4. Configuring IP Forwarding Policies
- 3.4.1. Configuring IP Masquerade on Linux 2.4.x Kernels
- 3.4.2. Configuring IP Masquerade on Linux 2.2.x Kernels
- 3.4.3. Configuring IP Masquerade on Linux 2.0.x Kernels
-
-
-
-
-4. Configuring the other internal to-be MASQed machines
- 4.1. Configuring Microsoft Windows 95 and OSR2
- 4.2. Configuring Windows NT
- 4.3. Configuring Windows for Workgroup 3.11
- 4.4. Configuring UNIX Based Systems
- 4.5. Configuring DOS using NCSA Telnet package
- 4.6. Configuring MacOS Based System Running MacTCP
- 4.7. Configuring MacOS Based System Running Open Transport
- 4.8. Configuring Novell network using DNS
- 4.9. Configuring OS/2 Warp
- 4.10. Configuring OS/400 on a IBM AS/400
- 4.11. Configuring Other Systems
-
-
-5. Testing IP Masquerade
- 5.1. Loading up the rc.firewall ruleset
- 5.2. Testing internal MASQ client PC connectivity
- 5.3. Testing internal MASQ client to MASQ server connectivity
- 5.4. Testing internal MASQ server connectivity
- 5.5. Testing internal MASQ server to MASQ client connectivity
- 5.6. Testing External MASQ server Internet connectivity
- 5.7. Testing internal MASQ client to external MASQ server connectivity
- 5.8. Testing external MASQ ICMP forwarding
- 5.9. Testing MASQ functionality without DNS
- 5.10. Testing MASQ functionality with DNS resolution
- 5.11. Testing more MASQ functionality with DNS
- 5.12. Any remaining functional, performance, etc. issues...
-
-
-6. Other IP Masquerade Issues and Software Support
- 6.1. Problems with IP Masquerade
- 6.2. Incoming services
- 6.3. Supported Client Software and Other Setup Notes
- 6.3.1. Network Clients that -Work- with IP Masquerade
- 6.3.2. Clients that do not have full support in IP MASQ:
-
-
- 6.4. Stronger firewall rulesets to run after initial testing
- 6.4.1. Stronger IP Firewall (IPTABLES) rulesets
- 6.4.2. Stronger IP Firewall (IPCHAINS) rulesets
- 6.4.3. Stronger IP Firewall (IPFWADM) Rulesets
-
-
- 6.5. IP Masquerading multiple internal networks
- 6.6. IP Masquerade and Dial-on-Demand Connections
- 6.7. IPPORTFW, IPMASQADM, IPAUTOFW, REDIR, UDPRED, and other Port
- Forwarding tools
- 6.7.1. 2.4.x PORTFWD'ing: Using IPTABLE's PREROUTING option for 2.4.x
- kernels
- 6.7.2. 2.2.x PORTFWD'ing: Using IPMASQADM with 2.2.x kernels
- 6.7.3. 2.0.x PORTFWD'ing: Using IPPORTFW on 2.0.x kernels
-
-
- 6.8. CU-SeeMe and Linux IP-Masquerade
- 6.9. Mirabilis ICQ
- 6.10. Gamers: The LooseUDP patch
-
-
-7. Frequently Asked Questions
- 7.1. ( Distro ) - What Linux Distributions support IP Masquerading?
- 7.2. ( Requirements ) - What are the minimum hardware requirements and
- any limitations for IP Masquerade? How well does it perform?
- 7.3. ( Errors ) - When I run the rc.firewall command, I get "command not
- found" errors. Why?
- 7.4. ( Still wont work ) - I've checked all my configurations, I still
- can't get IP Masquerade to work. What should I do?
- 7.5. ( Email list ) - How do I join or view the IP Masquerade and/or IP
- Masqurade Developers mailing lists and archives?
- 7.6. ( NAT vs. Proxy ) - How does IP Masquerade differ from Proxy or NAT
- services?
- 7.7. ( GUI ) - Are there any GUI firewall creation/management tools?
- 7.8. ( MASQ and Dynamic IPs ) - Does IP Masquerade work with dynamically
- assigned IP addresses?
- 7.9. ( MASQ and various networks ) - Can I use a cable modem (both
- bi-directional and with modem returns), DSL, satellite link, etc. to
- connect to the Internet and use IP Masquerade?
- 7.10. ( Dial on Demand ) - Can I use Diald or the Dial-on-Demand feature
- of PPPd with IP MASQ?
- 7.11. ( Apps ) - What applications are supported with IP Masquerade?
- 7.12. ( Distro Setup ) - How can I get IP Masquerade running on Redhat,
- Debian, Slackware, etc.?
- 7.13. ( Timeouts ) - Connections seem to break if I don't use them often.
- Why is that?
- 7.14. ( Odd Behavior ) - When my Internet connection first comes up,
- nothing works. If I try again, everything then works fine. Why is
- this?
- 7.15. ( MTU ) - IP MASQ seems to be working fine but some sites don't
- work. This usually happens with WWW and some FTP sites.
- 7.15.1. Enabling PMTU Clamping for PPPoE and some PPP Users:
- 7.15.2. Clamping the MSS via IPTABLES:
- 7.15.3. Changing the External MTU of the MASQ server:
- 7.15.4. Changing the MTU of various operating systems:
-
-
- 7.16. ( FTP ) - MASQed FTP clients don't work.
- 7.17. ( Performance ) - IP Masquerading seems slow
- 7.18. ( PORTFW ) - IP Masquerading with PORTFWing seems to break when my
- line is idle for long periods
- 7.19. ( PORTFW - Locally ) - I can't reach my PORTFWed server from the
- INTERNAL lan
- 7.20. ( Logs ) - Now that I have IP Masquerading up, I'm getting all
- sorts of weird notices and errors in the SYSLOG log files. How do I
- read the IPTABLES/IPCHAINS/IPFWADM firewall errors?
- 7.21. ( Log Reduction ) - My logs are filling up with packet hits due to
- the new "stronger" rulesets. How can I fix this?
- 7.22. ( MASQ Security ) - Can I configure IP MASQ to allow Internet users
- to directly contact internal MASQed servers?
- 7.23. ( Free Ports ) - I'm getting "kernel: ip_masq_new(proto=UDP): no
- free ports." in my SYSLOG files. Whats up?
- 7.24. ( SETSOCKOPT ) - I'm getting "ipfwadm: setsockopt failed: Protocol
- not available" when I try to use IPPORTFW!
- 7.25. ( SAMBA ) - Microsoft File and Print Sharing and Microsoft Domain
- clients don't work through IP Masq!
- 7.26. ( IDENT ) - IRC won't work properly for MASQed IRC users. Why?
- 7.27. ( IRC DCC ) - mIRC doesn't work with DCC Sends
- 7.28. ( IP Aliasing ) - Can IP Masquerade work with only ONE Ethernet
- network card?
- 7.29. ( Multiple-LANs ) - I have two MASQed LANs but they cannot
- communicate with each other!
- 7.30. ( SHAPING ) - I want to be able to limit the speed of specific
- types of traffic
- 7.31. ( ACCOUNTING ) - I need to do accounting on who is using the
- network
- 7.32. ( MULTIPLE IPs - DMZ segments) - I have several EXTERNAL IP
- addresses that I want to PORTFW to several internal machines. How do
- I do this?
- 7.33. ( Netstat ) - I'm trying to use the NETSTAT command to show my
- Masqueraded connections but its not working
- 7.34. ( VPNs ) - I would like to get Microsoft PPTP (GRE tunnels) and/or
- IPSEC (Linux SWAN) tunnels running through IP MASQ
- 7.35. ( Games ) - I want to get the XYZ network game to work through IP
- MASQ but it won't work. Help!
- 7.36. ( Stops working ) - IP MASQ works fine for a while but then it
- stops working. A reboot seems to fix this. Why?
- 7.37. ( SMTP Relay ) - Internal MASQed computers cannot send SMTP or
- POP-3 mail!
- 7.38. ( Source Routing ) - I need different internal MASQed networks to
- exit on different external IP addresses
- 7.39. ( IPCHAINS rulesets on 2.4.x kernels ) - What the ipchains.o module
- can do on 2.4.x kernels
- 7.40. ( IPTABLES vs. IPCHAINS vs. IPFWADM ) - Why do the 2.4.x, 2.2.x,
- and 2.0.x kernels use different firewall systems?
- 7.41. ( Upgrades ) - I've just upgraded to the x.y.z kernel, why isn't IP
- Masquerade working?
- 7.42. ( EQL ) - I need help with EQL connections and IP Masq
- 7.43. ( Wussing out ) - I can't get IP Masquerade to work! What options
- do I have for Windows Platforms?
- 7.44. ( Developers ) - I want to help with IP Masquerade development.
- What can I do?
- 7.45. ( More INFO ) - Where can I find more information on IP Masquerade?
- 7.46. ( Translators ) - I want to translate this HOWTO to another
- language, what should I do?
- 7.47. ( Updates ) - This HOWTO seems out of date, are you still
- maintaining it? Can you include more information on ...? Are there
- any plans for making this better?
- 7.48. ( Thanks ) - I got IP Masquerade working, it's great! I want to
- thank you guys, what can I do?
-
-
-8. Miscellaneous
- 8.1. Useful Resources
- 8.2. Linux IP Masquerade Resource
- 8.3. Thanks to the following supporters..
- 8.4. Reference
- 8.5. ChangeLOG
-
-
-
------------------------------------------------------------------------------
-Chapter 1. Introduction
-
-1.1. Introduction to IP Masquerading or IP MASQ
-
-This document describes how to enable the Linux IP Masquerade feature on a
-given Linux host. IP Masquerade, called "IPMASQ" or "MASQ" for short, is a
-form of Network Address Translation (NAT) which allows internally connected
-computers that do not have one or more registered Internet IP addresses to
-communicate to the Internet via the Linux server's Internet IP address. Since
-IPMASQ is a generic technology, you can connect the Linux server's internal
-and external to other computers through LAN technologies like Ethernet,
-TokenRing, and FDDI, as well as dialup connections line PPP or SLIP links.
-This document primarily uses Ethernet and PPP connections in examples because
-it is most commonly used with DSL / Cablemodems and dialup connections.
-
-"This document is intended for systems running stable Linux kernels like
-2.4.x, 2.2.x, and 2.0.x preferably on an IBM-compatible PC. IP Masquerade
-does work on other Linux-supported platforms like Sparc, Alpha, PowerPC, etc.
-but this HOWTO doesn't cover them in as much detail. Beta kernels such as
-2.5.x, 2.3.x, 2.1.x, and ANY kernels less than 2.0.x are NOT covered in this
-document. The primary reason for this is because many of the older kernels
-are considered broken. If you are using an older kernel version, it is highly
-advisable to upgrade to one of the stable Linux kernels before using IP
-Masquerading. "
------------------------------------------------------------------------------
-
-1.2. Foreword, Feedback & Credits
-
-From the original IPMASQ HOWTO author:
-
-"As a new user, I found it very confusing to setup IP masquerade on the Linux
-kernel, (back then, its was a 1.2.x kernel). Although there was a FAQ and a
-mailing list, there was no documentation dedicated to this. There was also
-some requests on the mailing list for a HOWTO manual. So, I decided to write
-this HOWTO as a starting point for new users and possibly create a building
-block for other knowledgeable users. If you, the reader, have any additional
-ideas, corrections, or questions about this document, please feel free to
-contact us. "
-
-This document was originally written by [mailto:ambrose@writeme.com] Ambrose
-Au back in August, 1996, based on the 1.x kernel IPMASQ FAQ written by Ken
-Eves and numerous helpful messages from the original IP Masquerade mailing
-list. In particular, a mailing list message from Matthew Driver inspired
-Ambrose to set up IP Masquerade and eventually write version 0.80 of this
-HOWTO. In April 1997, Ambrose created the Linux IP Masquerade Resource Web
-site at [http://ipmasq.webhop.net] http://ipmasq.webhop.net which has
-provided up-to-date information on Linux IP Masquerading ever since. In
-February 1999, [dranch@trinnet.net] David Ranch took over maintenance of the
-HOWTO. David then re-wrote the HOWTO and added a substantial number of
-sections to the document. Today, the HOWTO is still maintained by David where
-he constantly updates it and fixes any reported bugs, etc.
-
-Please feel free to send any feedback or comments regarding this HOWTO to
-[mailto:dranch@trinnet.net] dranch@trinnet.net if you have any corrections or
-if any information/URLs/etc. is missing. Your invaluable feedback will
-certainly influence the future of this HOWTO!
-
-This HOWTO is meant to be a fairly comprehensive guide to getting your Linux
-IP Masquerading system working in the shortest time possible. David only
-plays a technical writer on T.V. so you might find the information in this
-document not as general and/or objective as it could be. If you think a
-section could be clearer, etc.. please let David know. The latest version of
-the MASQ HOWTO can be found at [http://www.ecst.csuchico.edu/~dranch/LINUX/
-index-linux.html#ipmasq] Dranch's Linux Page. Additional news, mirrors of the
-HOWTO, and information regarding IPMASQ can be found at the [http://
-ipmasq.webhop.net/] IP Masquerade Resource web page. If you have any
-technical questions on IP Masquerade, please join the [http://
-home.indyramp.net/mailman/listinfo/masq] IP Masquerade Mailing List instead
-of sending email to David or Ambrose. Most MASQ problems are -common- for ALL
-MASQ users and can be easily solved by users on the list. In addition to
-this, the response time of the IP MASQ email list will be much faster than a
-reply from either David or Ambrose.
-
-The latest version of this document can be found at the following sites which
-also contains HTML, Postscript, PDF, etc. versions
-
- * [http://www.ecst.csuchico.edu/~dranch/LINUX/index-linux.html#ipmasq]
- Dranch's Linux page
-
- * http://ipmasq.webhop.net/: The IP Masquerade Resources
-
- * http://ipmasq2.webhop.net/: The IP Masquerade Resources MIRROR
-
- * [http://www.tldp.org] The Linux Documentation Project
-
- * Also refer to IP Masquerade Resource Mirror Sites Listing for other local
- mirrored sites.
-
-
------------------------------------------------------------------------------
-1.3. Copyright & Disclaimer
-
-This document is copyrighted(c) 2003,2002,2001,2000 for David A. Ranch and it
-is a FREE document. You may redistribute it under the terms of the GNU
-General Public License (GPL).
-
-The information herein this document is, to the best of David's knowledge,
-correct. However, the Linux IP Masquerade feature is written by humans and
-thus, the chance of mistakes, bugs, etc. might occur from time to time.
-
-No person, group, or other body is responsible for any damage on your
-computer(s) and any other losses by using the information on this document.
-i.e.
-
-"THE AUTHORS AND ALL MAINTAINERS ARE NOT RESPONSIBLE FOR ANY DAMAGES INCURRED
-DUE TO ACTIONS TAKEN BASED ON THE INFORMATION IN THIS DOCUMENT. "
-
-Ok, with all this behind us... On with the show..
------------------------------------------------------------------------------
-
-Chapter 2. Background Knowledge
-
-2.1. What is IP Masquerade?
-
-IP Masquerade is a networking function in Linux similar to the one-to-many
-(1:Many) NAT (Network Address Translation) servers found in many commercial
-firewalls and network routers. For example, if a Linux host is connected to
-the Internet via PPP, Ethernet, etc., the IP Masquerade feature allows other
-"internal" computers connected to this Linux box (via PPP, Ethernet, etc.) to
-also reach the Internet as well. Linux IP Masquerading allows for this
-functionality even though these internal machines don't have an officially
-assigned IP address.
-
-MASQ allows a set of machines to invisibly access the Internet via the MASQ
-gateway. To other machines on the Internet, the outgoing traffic will appear
-to be from the IP MASQ Linux server itself. In addition to the added
-functionality, IP Masquerade provides the foundation to create a HEAVILY
-secured networking environment. With a well built firewall, breaking the
-security of a well configured masquerading system and internal LAN should be
-considerably difficult to accomplish.
-
-If you would like to know more on how MASQ (1:Many) differs from 1:1 (true)
-NAT and Proxy solutions, please see the Section 7.6 FAQ entry.
------------------------------------------------------------------------------
-
-2.2. Current Status
-
-IP Masquerade has been in the Linux kernels for several years now and is
-quite mature as the kernel enters the 2.4.x stage. Kernels since Linux 1.3.x
-have had MASQ support built-in. Today, many individuals and commercial
-businesses are using it with excellent results.
-
-2.4.x kernel users:
-
- * The 2.4.x kernel hosts an entirely re-written set of NAT code which is
- both far superior, faster, and more secure than any previous versions
- written for Linux. Unfortunately, several kernel modules that were
- written for the 2.2.x kernel to support things like UDP-based RealAudio,
- etc. have not been ported to 2.4.x yet. Because of this, some people
- should consider NOT upgrading if these network applications are critical
- to them. But, at the same time, some of these programs have been updated
- and now use different, NAT-friendly protocols. Thus special NAT treatment
- is no longer required. As always, please see the http://ipmasq.webhop.net
- /: The IP Masquerade Resources site for updated news, etc.
-
-
-Common network functionalities like Web browsing, telnet, ssh, ping,
-traceroute, etc. work well over stock IP Masquerade setups. Other network
-applications such as ftp, irc, and Real Audio work well with the appropriate
-additional IP MASQ modules loaded into the kernel as modules. Other
-network-specific programs like streaming audio (MP3s, True Speech, etc)
-should work too without any special module. Some users on the mailing list
-also had good results with video conferencing software.
-
-It should be noted that running IP Masquerade with only ONE network card
-(NIC) to MASQ between internal and external Ethernet networks is NOT
-recommended. For more details, please see Section 7.28 FAQ section.
-
-Anyways, please refer to Section 6.3 for a more complete listing of software
-supported by IP Maquerade all kernel versions.
-
-IP Masquerade works well as a server to other 'client machines' running
-various operating systems and hardware platforms. Here is a sampling of
-successful reports with internal MASQed systems running :
-
-
-
- * UNIX: Sun Solaris, [Net,Free,Open,*i]-BSD, Hp-UX, Linux, IBM AIX, Digital
- UNIX, Ultrix, etc.
-
- * Microsoft Windows 2000, NT (3.x and 4.x), 95/98/ME, Windows for
- Workgroups (with the TCP/IP package)
-
- * IBM OS/2
-
- * Apple Macintosh MacOS machines running either MacTCP or Open Transport
-
- * DOS-based systems with packet drivers and the NCSA Telnet package
-
- * VAXen
-
- * Compaq/Digital Alpha running Linux and NT
-
- * Amiga computers with AmiTCP or AS225-stack.
-
-
-
-
-The list goes on and on but the point is, if your OS platform talks TCP/IP,
-it should work with Linux's IP Masquerade!
------------------------------------------------------------------------------
-
-2.3. Who Can Benefit From IP Masquerade?
-
-
-
- * If you have a Linux host connected to the Internet and..
-
- * if you have internal computers running TCP/IP connected that are
- connected to this Linux box via on a network, and/or
-
- * if your Linux host has more than one modem and acts as a PPP or SLIP
- server connected to other computers, and these machines do not have
- official or public assigned IP addresses (i.e. addressed with private TCP
- /IP numbers).
-
- * If you want those OTHER machines to communicate to the Internet without
- spending extra money to acquire additional Public / Official TCP/IP
- addresses from your ISP, then you should either configure Linux to be a
- router or purchase an external router.
-
-
-
------------------------------------------------------------------------------
-
-2.4. Who Doesn't Need IP Masquerade?
-
-
-
- * If your machine is a stand-alone Linux host connected to the Internet
- (setting up a firewall is a good idea though), or
-
- * if you already have multiple assigned public addresses for your OTHER
- machines, and
-
- * if you don't like the idea of a 'free ride' using Linux and feel more
- comfortable using expensive commercial tools to perform the exact same
- functionalities.
-
-
-
------------------------------------------------------------------------------
-
-2.5. How does IP Masquerade Work?
-
-Based from the original IP Masquerade FAQ by Ken Eves: Here is a drawing of
-the most simplistic setup:
-+---------------------------------------------------------------------------+
-|PPP/ETH/etc. +------------+ +-------------+ |
-|to ISP provider | Linux #1 | PPP/ETH/etc. | Anybox | |
-| | | | | |
-| <---------- modem1| |modem2 ----------- modem3| | |
-| | | | | |
-| 111.222.121.212 | | 192.168.0.100 | | |
-| +------------+ +-------------+ |
-+---------------------------------------------------------------------------+
-
-In the above drawing, a Linux box with IP_MASQUERADING is installed as Linux
-#1 and is connected to the Internet via PPP, Ethernet, etc. It has an
-assigned public IP address of 111.222.121.212. It also has another network
-interface (e.g. modem2) connected to allow incoming network traffic be it
-from a PPP connection, Ethernet connection, etc.
-
-The second system (which does not need to be Linux) connects into the Linux #
-1 box and starts its network traffic to the Internet. This second machine
-does NOT have a publicly assigned IP address from the Internet, so it uses an
-[http://www.ietf.org/rfc/rfc1918.txt?number=1918] RFC1918 private address,
-say 192.168.0.100. (see below for more info)
-
-With IP Masquerade and the routing configured properly, this second machine
-"Anybox" can interact with the Internet as if it was directly connected to
-the Internet with a few small exceptions [noted later].
-
-Quoting Pauline Middelink (the founder of Linux's IPMASQ):
-
-"Do not forget to mention that the "ANYBOX" machine should have the Linux #1
-box configured as its default gateway (whether it be the default route or
-just a subnet is no matter). If the "ANYBOX" machine is connected via a PPP
-or SLIP connection, the Linux #1 machine should be configured to support
-proxy arp for all routed addresses. But, the setup and configuration of proxy
-arp is beyond the scope of this document. Please see the [http://www.tldp.org
-/HOWTO/PPP-HOWTO/index.html] PPP-HOWTO for more details."
-
-The following is an excerpt on how IPMASQ briefly works though this will be
-explained in more detail later. This short text is based from a previous post
-on comp.os.linux.networking which has been edited to match the names used in
-the above example:
-+-------------------------------------------------------------------------------+
-| o I tell machine ANYBOX that my PPP or Ethernet connected Linux box is its |
-| gateway. |
-| |
-| o When a packet comes into the Linux box from ANYBOX, it will assign the |
-| packet to a new TCP/IP source port number and insert its own IP address |
-| inside the packet header, saving the originals. The MASQ server will |
-| then send the modified packet over the PPP/ETH interface onto the |
-| Internet. |
-| |
-| o When a packet returns from the Internet into the Linux box, Linux |
-| examines if the port number is one of those ports that was assigned |
-| above. If so, the MASQ server will then take the original port and |
-| IP address, put them back in the returned packet header, and send |
-| the packet to ANYBOX. |
-| |
-| o The host that sent the packet will never know the difference. |
-+-------------------------------------------------------------------------------+
-
-Another IP Masquerading Example:
-
-A typical example is given in the diagram below:
-+---------------------------------------------------------------------------+
-| Ethernet |
-| 192.168.0.x |
-| +----------+ |
-| | | |
-| | A-box |:::::: |
-| | |.2 : |
-| +----------+ : |
-| : +----------+ PPP/ETH |
-| +----------+ : .1 | Linux | link |
-| | | :::::::| Masq-Gate|:::::::::::::::::::>> Internet |
-| | B-box |:::::: | | 111.222.121.212 |
-| | |.3 : +----------+ |
-| +----------+ : |
-| : |
-| +----------+ : |
-| | | : |
-| | C-box |:::::: |
-| | |.4 |
-| +----------+ |
-| |
-| |
-| | | | > |
-| | <-Internal Network--> | | <- External Network ----> > |
-| | connected via an | | Connected from the > |
-| | Ethernet hub or | | Linux server to your > |
-| | switch | | Internet connection > |
-+---------------------------------------------------------------------------+
-
-In this example, there are (4) computer systems that we are concerned about.
-There is also presumably something on the far right that your PPP/ETH
-connection to the Internet comes through (modem server, DSL DSLAM, Cablemodem
-router, etc.). Out on the Internet, there exists some remote host (very far
-off to the right of the page) that you are interested in communicating with).
-The Linux system named Masq-Gate is the IP Masquerading gateway for ALL
-internal networked machines. In this example, the machines A-box, B-box, and
-C-box would have to go through the Masq-Gate to reach the Internet. The
-internal network uses one of several [http://www.cis.ohio-state.edu/cgi-bin/
-rfc/rfc1918.html] RFC-1918 assigned private network addresses, where in this
-case, would be the Class-C network 192.168.0.0. If you aren't familiar with
-RFC1918, it is encouraged to read the first few chapters of the RFC but the
-jist of it is that the TCP/IP addresses 10.0.0.0/8, 172.16-31.0.0/12, and
-192.168.0.0/16 are reserved. When we say "reserved", we mean that anyone can
-use these addresses as long as they aren't routed over the Internet. ISPs are
-even allowed to use this private addressing space as long as they keep these
-addresses within their own networks and NOT advertise them to other ISPs.
-Unfortunately, this isn't always the case but thats beyond the scope of this
-HOWTO.
-
-Anyway, the Linux box in the diagram above has the TCP/IP address 192.168.0.1
-while the other systems has the addresses:
-
-
-
- * A-Box: 192.168.0.2
-
- * B-Box: 192.168.0.3
-
- * C-Box: 192.168.0.4
-
-
-
-
-The three machines, A-box, B-box and C-box, can have any one of several
-operating systems, just as long as they can speak TCP/IP. Some such as
-Windows 95, Macintosh MacTCP or OpenTransport , or even another Linux box
-have the ability to connect to other machines on the Internet. When running
-the IP Masquerade, the masquerading system or MASQ-gate converts all of these
-internal connections so that they appear to originate from the masq-gate
-itself. MASQ then arranges so that the data coming back to a masqueraded
-connection is relayed to the proper originating system. Therefore, the
-systems on the internal network are only able to see a direct route to the
-internet and are unaware that their data is being masqueraded. This is called
-a "Transparent" connection.
-
-NOTE: Please see Chapter 7 for more details on topics such as:
-
-
-
- * The differences between NAT, MASQ, and Proxy servers.
-
- * How packet firewalls work
-
-
-
------------------------------------------------------------------------------
-
-2.6. Requirements for IP Masquerade on Linux 2.4.x
-
-" ** Please refer to IP Masquerade Resource for the latest information. ** "
-
- * The newest 2.4.x kernels are now using both a completely new TCP/IP
- network stack as well as a new NAT sub-system called NetFilter. Within
- this NetFilter suite of tools, we now have a tool called IPTABLES for the
- 2.4.x kernels much like there was IPCHAINS for the 2.2.x kernels and
- IPFWADM for the 2.0.x kernels. The new IPTABLES system is far more
- powerful (combines several functions into one place like true NAT
- functionality), offers better security (stateful inspection), and better
- performance with the new 2.4.x TCP/IP stack. But this new suite of tools
- can be a bit complicated in comparison to older generation kernels.
- Hopefully, if you follow along with this HOWTO carefully, setting up
- IPMASQ won't be too bad. If you find anything unclear, downright wrong,
- etc. please email David about it.
-
- Unlike the migration to IPCHAINS from IPFWADM, the new NetFilter tool has
- kernel modules that can actually support older IPCHAINS and IPFWADM
- rulesets with minimal changes. So re-writing your old MASQ or firewall
- ruleset scripts is not longer required. BUT.. with the 2.4.x kernels, you
- cannot use the old 2.2.x MASQ modules like ip_masq_ftp, ip_masq_irc, etc.
- AND IPCHAINS is incompatible with the new IPTABLES modules like
- ip_conntrack_ftp, etc. So, what does this mean? It basically means that
- if you want to use IPMASQ or PORTFW functionality under a 2.4.x kernel,
- you shouldn't use IPCHAINS rules but IPTABLES ones instead. Please also
- keep in mind that there might be several benefits in performing a full
- ruleset re-write to take advantage of the newer IPTABLES features like
- stateful tracking, etc. but that is dependant upon how much time you have
- to migrate your old rulesets. Please see Section 7.39 for additional
- details.
-
-
-Some new 2.4.x functionalities include the following:
-
-PROs:
-
- * Lots of new protocols modules like: amanda, eggdrop, ipsec, ipv6,
- portscan, pptp, quota, rsh, talk, and tftp
-
- * TRUE 1:1 NAT functionality for those who have TCP/IP addresses and
- subnets to use (no more iproute2 commands)
-
- * Stateful application level (FTP, IRC, etc.) and stateful protocol level
- (TCP/UDP/ICMP) network traffic inspection
-
- * Built-in PORT Forwarding (no more ipmasqadm or ipportfw commands)
-
- * The built-in PORTFW'ing support works for both external and internal
- traffic. This means that users that have PORTFW for external traffic and
- REDIR for internal port redirection do not need to use two tools any
- more!
-
- * PORT Forwarding of FTP traffic to internal hosts is now completely
- supported and is handled in the conn_trak_ftp module
-
- * Full Policy-Based routing features (source-based TCP/IP address routing)
-
- * Compatibility with Linux's FastRoute feature for significantly faster
- packet forwarding (a.k.a Linux network switching).
-
- Note that this feature is still not compatible with packet filtering for
- strong firewall rulesets.
-
- * Fully supports TCP/IP v4, v6, and even DECnet (ack!)
-
- * Supports wildcard interface names like "ppp*" for serial interfaces like
- ppp0, ppp1, etc
-
- * Supports filtering on both input and output INTERFACES (not just IP
- addresses)
-
- * Source Ethernet MAC filtering
-
- * Denial of Service (DoS) packet rate limiting
-
- * Packet REJECTs now have user-selectable return ICMP messages
-
- * Variable levels of logging (different packets can go to different SYSLOG
- levels)
-
- * Other features like traffic mirroring, securing traffic per login, etc.
-
-
-
-
- CONs:
-
- * Netfilter is an entirely new architechure thus most of the older 2.2.x
- MASQ kernel modules written to make non-NAT friendly network applications
- work through IPMASQ need to be re-written for the 2.4.x kernels. Because
- of this, if you specifically need functionality from some of these
- modules (see below), you should stay with a 2.2.x kernel until these
- modules have been either ported or the application has been updated to
- use NAT-friendly protocols. If you are curious on the porting status of a
- given module, please email the author of the module and NOT David or
- Ambrose. We don't code.. we just document. :-)
-
- Here is the status of the known IP Masq kernel modules or patches as
- found on the IPMASQ WWW site's Application Support Matrix. In addition,
- you should also setup out the [http://www.netfilter.org/documentation/
- pomlist/pom-summary.html] Netfilter Patch-o-Matic URL as well. If you
- have the time and knowledge to help in the porting of code, your efforts
- would be highly appreciated:
- +----------------------------------------------------------------------------+
- | Status = Module name = Description and notes |
- |--------- ----------- ---------------------------------- |
- | Ported CuSeeme Used for Video conferencing |
- | |
- |NotPorted DirectPlay Used for online Microsoft-based games |
- | |
- | Ported FTP Used for file transfers |
- | - NOTEs: Built into the kernel and |
- | fully supports PORTFWed FTP |
- | |
- |ReWritten H.323 Used for Video conferencing |
- | |
- |NotPorted ICQ Used for Instant messaging |
- | * No longer required for modern ICQ clients |
- | |
- | Ported Irc Used for Online chat rooms |
- | |
- | Ported Quake Used for online Quake games |
- | |
- | Ported PPTP Allow for multiple clients to the same server |
- | |
- |NotPorted Real Audio Used for Streaming video / audio |
- | * No longer required for modern RealVideo clients |
- | |
- |NotPorted VDO Live Used for Streaming audio? |
- +----------------------------------------------------------------------------+
-
- Documentation on how to perform MASQ module porting is available at
- [http://www.netfilter.org/documentation/HOWTO/
- netfilter-hacking-HOWTO.html] http://www.netfilter.org/documentation/
- HOWTO/netfilter-hacking-HOWTO.html. If you have the time and knowledge,
- your talent would highly be appreciated in porting these modules.
-
-
-If you'd like to read up more on NetFilter and IPTables, please see: [http://
-www.netfilter.org/documentation/index.html#HOWTO] http://www.netfilter.org/
-documentation/index.html#HOWTO and more specifically [http://
-www.netfilter.org/documentation/HOWTO//NAT-HOWTO.html] http://
-www.netfilter.org/documentation/HOWTO//NAT-HOWTO.html
-
-Linux 2.4.x IP Masquerade requirements include:
-
- * Any decent computer hardware. See Section 7.2 for more details.
-
- * The 2.4.x kernel source is available from [http://www.kernel.org/] http:/
- /www.kernel.org/.
-
- NOTE: Most modern Linux distributions, Section 7.1, that natively come
- with 2.4.x kernels are typically modular kernels and have all the IP
- Masquerade functionality already included. In such cases, there is no
- need to compile a new Linux kernel. If you are UPGRADING your kernel, you
- should be aware of other programs that might be required and/or need to
- be upgraded as well (mentioned later in this HOWTO).
-
- * The program "iptables" version 1.2.4 or newer ( 1.2.7a or newer is highly
- recommended ) archive available from [http://www.netfilter.org/] http://
- www.netfilter.org/
-
- + NOTE #1: All versions of IPTABLES less than 1.2.3 have a FTP module
- issue that can bypass any existing firewall rulesets. ALL IPTABLES
- users are highly recommended to upgrade to the newest version. The
- URL is above.
-
- NOTE #2: All versions of IPTABLES less than 1.2.2 have a FTP "port"
- security vulnerability in the ip_conntrack_ftp module. All IPTABLES
- users are highly recommended to upgrade to the newest version. The
- URL is above.
-
- + This tool, much like the older IPCHAINS and IPFWADM tools enables the
- various Masquerding code, more advanced forms of NAT, packet
- filtering, etc. It also makes use of additional MASQ modules like the
- FTP and IRC modules. Additional information on version requirements
- for the newest IPTABLES howto, etc. is located at the [http://
- www.netfilter.org/] Unreliable IPTABLES HOWTOs page.
-
-
- * Loadable kernel modules, preferably 2.1.121 or higher, are available from
- [http://home.pi.se/blox/modutils/index.html] http://home.pi.se/blox/
- modutils/index.html or [ftp://ftp.kernel.org/pub/linux/utils/kernel/
- modutils ] ftp://ftp.kernel.org/pub/linux/utils/kernel/modutils
-
- * A properly configured and running TCP/IP network running on the Linux
- machine as covered in [http://www.tldp.org/HOWTO/Net-HOWTO/index.html]
- Linux NET HOWTO and the [http://www.tldp.org/LDP/nag2/index.html] Network
- Administrator's Guide . Also check out the [http://www.ecst.csuchico.edu/
- ~dranch/LINUX/index-linux.html#TrinityOS] TrinityOS document which is
- also authored by David Ranch. TrinityOS is a very comprehensive guide for
- Linux networking. Some topics include IP MASQ, security, DNS, DHCP,
- Sendmail, PPP, Diald, NFS, IPSEC-based VPNs, and performance sections, to
- name a few. There are over Fifty sections in all!
-
- * Connectivity to the Internet for your Linux host covered in Linux ISP
- Hookup HOWTO, [http://www.tldp.org/HOWTO/PPP-HOWTO/index.html] Linux PPP
- HOWTO, and [http://www.ecst.csuchico.edu/~dranch/LINUX/index-linux.html#
- TrinityOS] TrinityOS. Other helpful HOWTOs could include: Linux DHCP
- mini-HOWTO, [http://www.tldp.org/HOWTO/Cable-Modem/index.html] Linux
- Cable Modem mini-HOWTO and [http://www.tldp.org/HOWTO/DSL-HOWTO/
- index.html] http://www.tldp.org/HOWTO/DSL-HOWTO/index.html
-
- * Know how to configure, compile, and install a new Linux kernel as
- described in the Linux Kernel HOWTO. This HOWTO does cover kernel
- compiling but only for IP Masquerade related options.
-
-
------------------------------------------------------------------------------
-2.7. Requirements for IP Masquerade on Linux 2.2.x
-
-" ** Please refer to IP Masquerade Resource for the latest information. ** "
-
-
-
- * Any decent computer hardware. See Section 7.2 for more details.
-
- * The 2.2.x kernel source is available from [http://www.kernel.org/] http:/
- /www.kernel.org/.
-
- NOTE: Most modern Linux distributions, Section 7.1, that natively come
- with 2.2.x kernels are typically modular kernels and have all the IP
- Masquerade functionality already included. In such cases, there is no
- need to compile a new Linux kernel. If you are UPGRADING your kernel, you
- should be aware of other programs that might be required and/or need to
- be upgraded as well (mentioned later in this HOWTO).
-
- + NOTE #1: --- UPDATE YOUR KERNEL --- Linux 2.2.x kernels less than
- version 2.2.20 contain several different security vulnerabilities
- (some were MASQ specific). Kernels less than 2.2.20 have a few local
- vulnerabilities. Kernel versions less than 2.2.16 have a TCP root
- exploit vulnerability and versions less than 2.2.11 have a IPCHAINS
- fragmentation bug. Because of these issues, users running a firewall
- with strong IPCHAINS rulesets are open to possible instrusion. Please
- upgrade your kernel to a fixed version.
-
-
- * NOTE #2: Some newer Section 7.1 such as Redhat 5.2 might not be Linux
- 2.2.x ready (upgradable). Tools like DHCP, NetUtils, etc. will need to be
- upgraded. More details can be found later in the HOWTO.
-
- * Loadable kernel modules, preferably 2.1.121 or higher, are available from
- [http://home.pi.se/blox/modutils/index.html] http://home.pi.se/blox/
- modutils/index.html or [ftp://ftp.kernel.org/pub/linux/utils/kernel/
- modutils ] ftp://ftp.kernel.org/pub/linux/utils/kernel/modutils
-
- * A properly configured and running TCP/IP network running on the Linux
- machine as covered in [http://www.tldp.org/HOWTO/Net-HOWTO/index.html]
- Linux NET HOWTO and the [http://www.tldp.org/LDP/nag2/index.html] Network
- Administrator's Guide . Also check out the [http://www.ecst.csuchico.edu/
- ~dranch/LINUX/index-linux.html#TrinityOS] TrinityOS document which is
- also authored by David Ranch. TrinityOS is a very comprehensive guide for
- Linux networking. Some topics include IP MASQ, security, DNS, DHCP,
- Sendmail, PPP, Diald, NFS, IPSEC-based VPNs, and performance sections, to
- name a few. There are over Fifty sections in all!
-
- * Connectivity to the Internet for your Linux host covered in Linux ISP
- Hookup HOWTO, [http://www.tldp.org/HOWTO/PPP-HOWTO/index.html] Linux PPP
- HOWTO, and [http://www.ecst.csuchico.edu/~dranch/LINUX/index-linux.html#
- TrinityOS] TrinityOS. Other helpful HOWTOs could include: Linux DHCP
- mini-HOWTO, [http://www.tldp.org/HOWTO/Cable-Modem/index.html] Linux
- Cable Modem mini-HOWTO and [http://www.tldp.org/HOWTO/DSL-HOWTO/
- index.html] http://www.tldp.org/HOWTO/DSL-HOWTO/index.html
-
- * IP Chains 1.3.10 or newer are available from [http://www.netfilter.org/
- ipchains/] http://www.netfilter.org/ipchains/. Additional information on
- version requirements for the newest IPCHAINS HOWTO, etc is located at the
- Linux IP Chains page (mirror at Samba.org)
-
- * Know how to configure, compile, and install a new Linux kernel as
- described in the Linux Kernel HOWTO. This HOWTO does cover kernel
- compiling but only for IP Masquerade related options.
-
-
-Other optional patches and tools for 2.2.x kernels
-
- * TCP/IP port-forwarding or re-directing:
-
- + IP PortForwarding (IPMASQADM) - RECOMMENDED, IPMASQADM mirror.
-
-
- * PORTFW FTP Solutions:
-
- + There are 2.2.x and 2.0.x kernel MASQ Module solutions for PORTFWed
- FTP to a MASQed machine (put an FTP server behind a MASQ server).
- Please see the Application Page on the [http://ipmasq.webhop.net]
- IPMASQ WWW site for full details. Please note that this is not
- required for 2.4.x kernels.
-
- There is a full FTP proxy application from SuSe that will also allow
- PORTFWed-like functionality to reach an internal FTP server. For more
- details, please refer to the SuSe Proxy URL.
-
-
- * IPROUTE2 for True 1:1 NAT, Policy-based (source) routing, and Traffic
- Shaping:
-
- + ftp://ftp.inr.ac.ru/ip-routing
-
- + Documentation can be found at [http://www.compendium.com.ar/
- policy-routing.txt] http://www.compendium.com.ar/policy-routing.txt
-
- + The [http://www.tldp.org/HOWTO/Adv-Routing-HOWTO/index.html] Advanced
- Routing HOWTO
-
- + Some source code mirrors are at:
-
- [ftp://ftp.funet.fi/pub/mirrors/ftp.inr.ac.ru/ip-routing/] ftp://
- ftp.funet.fi/pub/mirrors/ftp.inr.ac.ru/ip-routing/ (STM1 to USA) ---
- [ftp://sunsite.icm.edu.pl/pub/Linux/iproute/] ftp://
- sunsite.icm.edu.pl/pub/Linux/iproute/
-
- [ftp://ftp.sunet.se/pub/Linux/ip-routing/] ftp://ftp.sunet.se/pub/
- Linux/ip-routing/ --- [ftp://ftp.nvg.ntnu.no/pub/linux/ip-routing/]
- ftp://ftp.nvg.ntnu.no/pub/linux/ip-routing/
-
- [ftp://ftp.crc.ca/pub/systems/linux/ip-routing/] ftp://ftp.crc.ca/pub
- /systems/linux/ip-routing/ --- [ftp://ftp.paname.org] ftp://
- ftp.paname.org (France)
-
-
-
-Please see the [http://ipmasq.webhop.net/] IP Masquerade Resource page for
-more information available on these patches and possibly others as well.
------------------------------------------------------------------------------
-
-2.8. Requirements for IP Masquerade on Linux 2.0.x
-
-" ** Please refer to IP Masquerade Resource for the latest information. ** "
-
- * Any decent computer hardware. See Section 7.2 for more details.
-
- * The 2.0.x kernel source is available from [http://www.kernel.org/] http:/
- /www.kernel.org/.
-
- NOTE: Most modern Linux Section 7.1 that natively come with 2.0.x kernels
- are typically modular kernels and have all the IP Masquerade
- functionality already included. In such cases, there is no need to
- compile a new Linux kernel. If you are UPGRADING your kernel, you should
- be aware of other programs that might be required and/or need to be
- upgraded as well (mentioned later in this HOWTO).
-
- * Loadable kernel modules, preferably 2.1.85 or newer is available from
- [http://home.pi.se/blox/modutils/index.html] http://home.pi.se/blox/
- modutils/index.html or [ftp://ftp.kernel.org/pub/linux/utils/kernel/
- modutils ] ftp://ftp.kernel.org/pub/linux/utils/kernel/modutils
- (modules-1.3.57 is the minimal requirement)
-
- * A properly configured and running TCP/IP network running on the Linux
- machine as covered in Linux NET HOWTO and the [http://www.tldp.org/LDP/
- nag2/index.html] Network Administrator's GuideAlso check out the [http://
- www.ecst.csuchico.edu/~dranch/LINUX/index-linux.html#TrinityOS] TrinityOS
- document which is also authored by David Ranch. TrinityOS is a very
- comprehensive guide to Linux networking. Topics include IP MASQ,
- security, DNS, DHCP, Sendmail, PPP, Diald, NFS, IPSEC-based VPNs,
- performance issues, and many more. There exists over fifty sections in
- all!
-
- * Connectivity to the Internet for your Linux host is covered in Linux ISP
- Hookup HOWTO, [http://www.tldp.org/HOWTO/PPP-HOWTO/index.html] Linux PPP
- HOWTO, and [http://www.ecst.csuchico.edu/~dranch/LINUX/index-linux.html#
- TrinityOS] TrinityOS. Other helpful HOWTOs could include: Linux DHCP
- mini-HOWTO, [http://www.tldp.org/HOWTO/Cable-Modem/index.html] Linux
- Cable Modem mini-HOWTO and [http://www.tldp.org/HOWTO/DSL-HOWTO/
- index.html] Linux DSL HOWTO
-
- * Ipfwadm 2.3.0 or newer is available from [http://www.xos.nl/linux/ipfwadm
- /download.html] http://www.xos.nl/linux/ipfwadm/download.html
-
- * More information on version requirements are on the [http://www.xos.nl/
- linux/ipfwadm/] Linux IPFWADM page
-
- * If you are interested in running IPCHAINS on a 2.0.x+ kernel, see Willy
- Tarreau's IPCHAINS enabler for 2.0.36+ or Rusty's IPCHAINS for 2.0.x
- kernels. Please note that these patches are NOT compatible with the
- IPPORTFW patches for the 2.0.x kernels. Unfortunately, its an either/or
- deal.
-
- * Know how to configure, compile, and install a new Linux kernel as
- described in the [http://www.tldp.org/HOWTO/Kernel-HOWTO/index.html]
- Linux Kernel HOWTO. This HOWTO does cover kernel compiling but only for
- IP Masquerade related options.
-
-
-Here is a list of IP Masquerading patches for 2.0.x kernels:
-
- * Steven Clarke's IP PortForwarding (IPPORTFW) - RECOMMENDED
-
- * [http://ipmasq.webhop.net/ipautofw.tar.gz] IP AutoForward - NOT
- Recommended
-
- * [http://ipmasq.webhop.net/redir_0.7.orig.tar.gz] REDIR for TCP (REDIR) -
- NOT Recommended unless required for internal PORTFW
-
- * [http://ipmasq.webhop.net/udpred.c.gz] UDP redirector (UDPRED) - NOT
- Recommended
-
- * PORTFWed FTP:
-
- + If you are going to port forward FTP traffic to an internal FTP
- server, you might need to download [http://ipmasq.webhop.net/files22/
- ip_masq-v0.27-for_2.2.18pre9.patch.gz] Fred Viles's FTP server patch
- The reason for "might" is that some users have had success without
- the use of these pathches, while others need it. Explicit details on
- this topic can be found in Section 6.7 of this HOWTO.
-
-
- * X-Windows display forwarders:
-
- + [ftp://sunsite.unc.edu/pub/Linux/X11/compress/dxpc-3.7.0.tar.gz]
- X-windows forwarding (DXCP)
-
-
- * PPTP (GRE) and SWAN (IPSEC) VPNs tunneling forwarders:
-
- + If you plan connecting an internal MASQed PC to a remote PPTP server,
- you MUST INSTALL the PPTP-Masquerade kernel patch available from the
- URLsbelow. If you plan on having external PPTP users connect to an
- internal masqueraded PPTP server, not only do you need the kernel
- patch installed but you also need PORTFW support enabled in the
- kernel. Please see the following URLs for the patches and more
- information:
-
- [http://www.impsec.org/linux/masquerade/ip_masq_vpn.html] John
- Hardin's VPN Masquerade forwarders or the old patch for just [http://
- ipmasq.webhop.net/ip_masq_pptp.patch.gz] PPTP Support.
-
-
- * Game specific patches:
-
- + Glenn Lamb's [http://ipmasq.webhop.net/files20/
- loose-udp-2.0.36.patch.gz] LooseUDP for 2.0.36+ patch.
-
-
-
------------------------------------------------------------------------------
-Chapter 3. Setting Up IP Masquerade
-
-3.1. Compiling a new kernel if needed
-
-If your private network contains any vital information, think carefully in
-terms of SECURITY before implementing IP Masquerade. By default, IP MASQ
-becomes a GATEWAY for you to get onto the Internet, but it also can allow
-someone from the Internet to possibly get into your internal network.
-
-Once you have IP MASQ functioning, it is HIGHLY recommended for the user to
-implement a STRONG IPFWADM/IPCHAINS firewall ruleset. Please see Section
-6.4.1, Section 6.4.2 and Section 6.4.3 located below for more details.
------------------------------------------------------------------------------
-
-3.2. Checking your existing kernel for MASQ functionality
-
-Almost ALL modern Linux distributions come MASQ-Ready these days but its
-always good to check your system before you try to set things up. Follow
-these few steps for your kernel to see if your kernel is MASQ ready.
-
-To see which kernel your system is running, run the following command:
-+---------------------------------------------------------------------------+
-|uname -a |
-+---------------------------------------------------------------------------+
-
-
-
- * Just for clarity: 2.4.x kernels run IPTABLES :: 2.2.x kernels run
- IPCHAINS :: 2.0.x kernels run IPFWADM
-
- * In general, you must have kernel support for:
-
- + IP forwarding
-
- + IP masquerading
-
- + IP Firewalling
-
- + etc.
-
-
-
-You will also need to have most MASQ-related modules compiled (most modular
-kernels will already have all you need already done. Then you will NOT need
-to re-compile the kernel. If you AREN'T SURE if your Linux distribution is
-MASQ ready, do the following:
-
- * 2.4.x kernels (look for most of the following entries out of the much
- longer list):
-
- + Run the command "ls /proc/sys/net/ipv4" while logged into the Linux
- box. These items are required and should be present regardless if
- your kernel built IPMASQ as modules or statically.
-
- o ip_dynaddr
-
- ip_forward
-
-
- + To check if IPMASQ was compiled statically into the kernel, run the
- command "/sbin/lsmod" and see if and modules like the ones shown
- below for the MODULE section are loaded. No? Ok, now run the command
- "ls /proc/net/" and see if you see additional /proc files such as:
-
- o ip_masquerade
-
- ip_conntrack
-
- ip_tables_names
-
- If you see these /proc entries and there WEREN'T any kernel modules
- loaded (shown via the "lsmod" command mentioned above), then your
- kernel has the IPTABLES subsystem statically compiled into it and is
- ready to go to use IPMASQ on this system.
- + If your kernel uses IPTABLES via modules, most of the stuff listed
- above should have been missing (because the modules probably aren't
- loaded). Run the command "ls /lib/modules/`uname -r`/kernel/net/ipv4/
- netfilter/" where you should see files like:
-
- o ip_conntrack.o, ip_conntrack_ftp.o, ip_conntrack_irc.o,
- ip_nat_ftp.o, ip_nat_irc.o
-
- ip_tables.o, ipt_MASQUERADE.o, iptable_nat.o, iptable_mangle.o,
- iptable_filter.o
-
- And some optional ones like: ipchains.o, ipt_REJECT.o, and
- ipt_tcpmss.o
-
- If you see those kernel files, IPTABLES was compiled using modules
- and things look ready to go to use IPMASQ on this system.
-
- * 2.2.x kernels (look for most of the following entries out of the much
- longer list): list):
-
- + Run the command "ls /proc/sys/net/ipv4" while logged into the Linux
- box. These items are required and should be present regardless if
- your kernel built IPMASQ as modules or statically.
-
- o ip_always_defrag
-
- ip_dynaddr
-
- ip_forward
-
- ip_masq_debug
-
- ip_masq_udp_dloose (some distros don't support this -- ignore it
- for now
-
- Other 2.2.x options can be checked by running "ls /proc/net/"
-
- # ip_fwchains
-
- ip_fwnames
-
- ip_masquerade
-
-
- Even more 2.2.x options can be checked by running "ls /proc/net/"
-
- # app
-
- icmp
-
- icq
-
- mfw
-
- portfw
-
- tcp
-
- udp/
-
-
-
-
- * 2.0.x kernels (look for most of the following entries out of the much
- longer list):
-
- + Run the command "ls /proc/sys/net/ipv4" while logged into the Linux
- box. These items are required and should be present regardless if
- your kernel built IPMASQ as modules or statically.
-
- o ip_dynaddr
-
- ip_forward
-
- running "ls /proc/net"
-
- # ip_forward
-
- ip_masq_app
-
- ip_masquerade
-
- ip_portfw
-
-
-
-
-
-Ultimately, it comes down to the fact if you see /proc files such as
-"iip_forward", "ip_masq_debug", "ip_masq_udp_dloose"(optional), and
-"ip_always_defrag" (optional) exist.
-
-So. Do most of the above /proc entries or kernel modules show up for your
-respective kernel? If so, thats good! If you cannot find any of the above
-entries or if you aren't sure if your distribution supports IP Masquerading
-by default, ASSUME IT DOESN'T SUPPORT MASQ. You can do one last check by
-looking at the Section 7.1 section and see if your Linux Distribution is
-listed. Still not there? Sounds like you'll need to compile a kernel but
-don't worry.. it isn't hard.
-
-Regardless if your current kernel has MASQ support or not, reading the
-remainder of this section is still highly recommended as it contains other
-useful information.
------------------------------------------------------------------------------
-
-3.2.1. Compiling Linux 2.4.x Kernels
-
- * First, you'll need to get some 2.4.x kernel sources (preferably the
- latest kernel version - NEWER *IS* BETTER IN LINUX LAND)
-
- + NOTE #1: As both the 2.4.x kernel train and the iptables program
- development progresses, the compile configurion options will change
- over time. As of this version of the IPMASQ howto, this section
- reflects the settings for IPTABLES 1.2.7a and the 2.4.20 kernel. If
- you are compiling against a newer or previous kernel or IPTABLES
- version, the dialogs and even commands might look different. It is
- recommended that you update to the newest versions of both the kernel
- and IPTABLES for added capability, performance, and stability of the
- kernel.
-
-
- * Next, depending on the version of the Linux kernel and IPTABLES archive
- you downloaded, you might want to apply some IPTABLES "patch-o-matic"
- patches against the kernel. These OPTIONAL patches might fix some known
- problems, add additional functionality you might need (H.323 protocol,
- specific issues with network games), etc. It should be noted that the
- Patch-O-Matic patches used to come with the IPTABLES archive. This is no
- longer the case and you have to download them (if any) seperately. You
- can find the the various URLs for downloading IPTABLES, the Patch-o-matic
- system, etc. Section 2.6.
-
- * If this is your first time compiling the kernel, don't be scared. In
- fact, it's rather easy and it's covered in several URLs found in Section
- 2.6. Please note that the instructions included here is just one way to
- do build a kernel. Please see the Kernel HOWTO for full details.
-
- NOTE: Please notice that it IS NOT recommended to put the new kernel
- sources into the /usr/src/linux directory. You should leave the original
- kernel sources that came with your Linux distribution in /usr/src/linux.
- For more details on this topic, please read the "README" file in the top
- level directory of the kernel sources.
-
- * For this HOWTO example, create a directory called /usr/src/kernel. Next,
- "cd" into this directory and download the newest 2.4.x kernel sources
- into it. Once downloaded, issue the following command (if the file ends
- in a .tar.gz): tar xvzf linux-2.4.x.tar.gz or (if the file ends in a
- .tar.bzip2): tar xyvf linux-2.4.x.tar.bz2. Please substitute the "x" in
- the 2.4.x filename with the Linux 2.4 kernel version you downloaded.
-
- BZ2 Note: Some Linux distributions use the "I" option instead of the "y"
- option to decompress bzip2 archives.
-
- Once uncompressed, I recommend that you rename the directory from the
- stock "linux" name to "linux-2.4.x" (replace the "x" with the specific
- version of your newly installed kernel) for clarity. To do this, run the
- command "mv linux linux-2.4.x". Next, make sure there is a directory or
- symbolic link pointing to "/usr/src/kernel/linux" ie. run the command:
- +---------------------------------------------------------------+
- |ln -s /usr/src/kernel/linux-2.4.x /usr/src/kernel/linux |
- +---------------------------------------------------------------+
- again subsituting the "x" for your proper kernel version.
-
- * As mentioned above, you might consider applying any appropriate or
- optional patches to the kernel's MASQ code BEFORE you compile the final
- kernel. The IP MASQ code found in the stock kernels is already very
- useful and does not require any specific patching in order for the system
- to work for NAT-friendly network applications. Many of these patches are
- only to fix possible known bugs, add new features (some are /very/ cool),
- etc. Please refer to Section 2.6 for URLs and the [http://
- ipmasq.webhop.net/] IP Masquerade Resources for up-to-date information
- and patch URLs.
-
- * Applying IPTABLES and Patch-o-Matic kernel patches
-
- Download the iptables package and optional Patch-O-matics from the
- Section 2.6 and put it into a directory, say "/usr/src/archive/
- netfilter". Next, go into this new netfilter directory and uncompress the
- iptables archive with the command:
-
- +---------------------------------------------------------------+
- |tar xyvf iptables-x.y.z.tar.bz2 |
- |tar xyvf patch-o-matic-x.tar.bz2 |
- +---------------------------------------------------------------+
-
- Now, go into the new iptables-x.y.x directory (/usr/src/archive/netfilter
- /iptables-x.y.z) and run the command
-
- +---------------------------------------------------------------+
- | #For iptables v1.2.7a: |
- | make KERNEL_DIR=/usr/src/kernel/linux |
- | |
- | #For iptables v1.2.4 (when Patch-o-matic was built-in): |
- | make pending-patches KERNEL_DIR=/usr/src/kernel/linux |
- | |
- +---------------------------------------------------------------+
-
- NOTE: this assumes that your 2.4.x kernel sources are in the /usr/src/
- kernel/linux directory.
-
- NOTE #2: If you append a "/" to the end of the above command line, you
- will get an error stating:
- +-----------------------------------------------------------------+
- |"make: *** [/usr/src/kernel/linux/include/asm/socket.h] Error 1".|
- +-----------------------------------------------------------------+
- Remove the trailing "/" and try again.
-
- Here is an example of compiling IPTABLES v1.2.7a. Your output might look
- different depending on what version you are trying to use.
-
- * +------------------------------------------------------------------------------+
- |# make KERNEL_DIR=/usr/src/kernel/linux |
- | |
- |Extensions found: |
- | |
- |cc -O2 -Wall -Wunused -I/usr/src/kernel/linux/include -Iinclude/ |
- |-DIPTABLES_VERSION=\"1.2.7a\" -fPIC -o extensions/libipt_ah_sh.o -c |
- |extensions/libipt_ah.c |
- |ld -shared -o extensions/libipt_ah.so extensions/libipt_ah_sh.o |
- |cc -O2 -Wall -Wunused -I/usr/src/kernel/linux/include -Iinclude/ |
- |-DIPTABLES_VERSION=\"1.2.7a\" -fPIC -o extensions/libipt_conntrack_sh.o -c |
- |extensions/libipt_conntrack.c |
- |ld -shared -o extensions/libipt_conntrack.so extensions/libipt_conntrack_sh.o |
- |cc -O2 -Wall -Wunused -I/usr/src/kernel/linux/include -Iinclude/ |
- |-DIPTABLES_VERSION=\"1.2.7a\" -fPIC -o extensions/libipt_dscp_sh.o -c |
- |extensions/libipt_dscp.c |
- |extensions/libipt_dscp_helper.c:69: warning: `dscp_to_name' defined but not |
- |used |
- |ld -shared -o extensions/libipt_dscp.so extensions/libipt_dscp_sh.o |
- |. |
- |. |
- |. |
- |cc -O2 -Wall -Wunused -I/usr/src/kernel/linux/include -Iinclude/ |
- |-DIPTABLES_VERSION=\"1.2.7a\" -c -o libipulog/libipulog.o |
- |libipulog/libipulog.c |
- |ar rv libipulog/libipulog.a libipulog/libipulog.o |
- |a - libipulog/libipulog.o |
- |rm libiptc/libip6tc.o libiptc/libip4tc.o libipulog/libipulog.o libipq/libipq.o|
- +------------------------------------------------------------------------------+
-
- * Ok, hopefully the IPTABLES program compiled up for you. Now, you need to
- install it. To do this, directory and run the command
-
- +---------------------------------------------------------------+
- | make install KERNEL_DIR=/usr/src/kernel/linux |
- +---------------------------------------------------------------+
-
- * Here is an example of installing IPTABLES v1.2.7a. Your output might look
- different depending on what version you are trying to use.
-
- * +------------------------------------------------------------------------------+
- |# make install KERNEL_DIR=/usr/src/kernel/linux |
- | |
- |cp iptables /usr/local/sbin/iptables |
- |cp iptables-save /usr/local/sbin/iptables-save |
- |cp iptables-restore /usr/local/sbin/iptables-restore |
- |cp ip6tables /usr/local/sbin/ip6tables |
- |cp extensions/libipt_ah.so /usr/local/lib/iptables/libipt_ah.so |
- |cp extensions/libipt_conntrack.so /usr/local/lib/iptables/libipt_conntrack.so |
- |cp extensions/libipt_dscp.so /usr/local/lib/iptables/libipt_dscp.so |
- |cp extensions/libipt_ecn.so /usr/local/lib/iptables/libipt_ecn.so |
- |cp extensions/libipt_esp.so /usr/local/lib/iptables/libipt_esp.so |
- |cp extensions/libipt_helper.so /usr/local/lib/iptables/libipt_helper.so |
- |. |
- |. |
- |. |
- |cp extensions/libip6t_udp.so /usr/local/lib/iptables/libip6t_udp.so |
- |cp extensions/libip6t_LOG.so /usr/local/lib/iptables/libip6t_LOG.so |
- |cp extensions/libip6t_MARK.so /usr/local/lib/iptables/libip6t_MARK.so |
- +------------------------------------------------------------------------------+
-
-
-Next, if you are interested in applying a Patch-O-Matic patch set, go into
-the patch-o-matic-X directory (/usr/src/archive/netfilter/patch-o-matic-X)
-and run the command
-
- * +----------------------------------------------------------------+
- | #For Patch-O-Matic later than the release of iptables v1.2.7a: |
- | KERNEL_DIR=/usr/src/kernel/linux |
- | ./runme pending |
- | |
- +----------------------------------------------------------------+
-
- NOTE #1: The use of the "pending" batch is the most common for IPMASQ
- functionality but there are several others. See below.
-
- NOTE #2: this assumes that your 2.4.x kernel sources are in the /usr/src/
- kernel/linux directory.
-
- NOTE #3: If you append a "/" to the end of the command line, you will get
- an error stating:
- +------------------------------------------------------------------+
- |"make: *** [/usr/src/kernel/linux/include/asm/socket.h] Error 1". |
- |Remove the trailing "/" and try again. |
- +------------------------------------------------------------------+
-
- Here is an example of the Patch-O-Matic prompts you might receive for a
- 2.4.20 kernel with the "20030107" Patch-O-Matic set. You can also run the
- "runme" program in a batch mode to speed things up, add experimental
- patches, etc. if you'd like. To better understand your options, simply
- run the "./runme" command by itself. Please note that these prompts WILL
- CHANGE over time.
-
- * +--------------------------------------------------------------------------------+
- |Welcome to Rusty's Patch-o-matic! |
- | |
- |Each patch is a new feature: many have minimal impact, some do not. |
- |Almost every one has bugs, so I don't recommend applying them all! |
- |------------------------------------------------------- |
- |Already applied: submitted/01_2.4.19 |
- | submitted/02_2.4.20 |
- | submitted/ipt_ULOG-mac_len-fix |
- | submitted/ipt_multiport-invfix |
- | pending/01_ip_conntrack_proto_tcp-lockfix |
- | pending/02_newnat-udp-helper |
- | pending/03_REJECT-fwspotting-phrack60-fix |
- | pending/04_ftp-conntrack-msg-fix |
- | |
- |Testing... 05_ECN-tcpchecksum-littleendian-fix.patch NOT APPLIED (1 rejects out |
- |of 1 hunks) |
- |The pending/05_ECN-tcpchecksum-littleendian-fix patch: |
- | Author: Patrick McHardy |
- | Status: Pending for kernel inclusion |
- | |
- | The 2.4.20 kernel included the new iptables 'ECN' target, enabling a |
- |selective |
- | ECN disable mechanism. Unfortunately there was a bug in the incremental |
- |TCP |
- | checksum update, resulting in broken TCP checksums on little endian |
- |machines. |
- | |
- | This patch fixes the Bug. |
- | |
- |Testing patch pending/05_ECN-tcpchecksum-littleendian-fix.patch... |
- | Patch pending/05_ECN-tcpchecksum-littleendian-fix.patch applied cleanly. |
- |Applying patch pending/05_ECN-tcpchecksum-littleendian-fix.patch... |
- | Patch pending/05_ECN-tcpchecksum-littleendian-fix.patch applied cleanly. |
- | |
- |Excellent! Kernel is now ready for compilation. |
- +--------------------------------------------------------------------------------+
-
- * If everything patches fine, you should see something like the text
-
- +---------------------------------------------------------------+
- |Excellent! Kernel is now ready for compilation. |
- +---------------------------------------------------------------+
-
- towards the bottom of the screen. Beyond that, you don't have to install
- anything at this point. The next step is to compile the new PATCHED
- kernel.
-
- * Ok, now the new kernel is ready to be compiled but you should make sure
- that you also have the proper matching iptables program on your machine
- too (just to make sure). Run the command:
-
- + +------------------------------------------------------------+
- |whereis iptables |
- +------------------------------------------------------------+
-
- and make sure its installed on the machine (the default place is in /usr/
- local/sbin/iptables. If you cannot find it or patched up your kernel
- sources as shown above, I recommend you just re-compile it up as shown
- above.
-
-Now that the kernel sources are patched up, you need to configure it to know
-what kinds of features you need (HD support, Networking support, MASQ
-support, etc.). Here are the MINIMUM kernel configuration options required to
-enable IP Masquerade functionality. Please understand that this HOWTO
-illustrates just ONE way to configure and compile a kernel (modules vs
-static). The main difference from this example vs. an example given by a
-different MASQ guide is that some people might wish to compile kernel
-components either as modules OR monolithically into the kernel. Basically,
-compiling things as modules gives you added flexibility to what is or isn't
-installed into the kernel (reduces unneeded memory use for things you aren't
-/ won't use and modules also allow for drop-in software upgrades [usually no
-need to reboot the machine]). On the flip side, kernel modules add more
-complexity to your configuration and sometimes the kernel auto-loader might
-make mistakes (not that I've ever seen this happen). Compiling things
-directly into the kernel makes things simpler BUT you loose a huge level of
-flexibility. The following kernel configuration example is a mixture of both
-a selection of kernel modules and building them in monolithically (you
-probably will ALWAYS need MASQ functionality ready to go).
-
- * Side Note: It is assumed that you will also configure the kernel to use
- your other installed hardware such as USB printers, Ethernet network
- interfaces, SCSI and IDE HD controllers, etc. as well. Please refer to
- the [http://www.tldp.org/HOWTO/Kernel-HOWTO/index.html] Linux Kernel
- HOWTO and the kernel source's "README" file and "Documentation/"
- directory for detailed help on compiling a kernel.
-
-
-You will need to answer either YES, NO, or MODULE to the following program.
-Not all options will be available without the proper kernel patches described
-later in this HOWTO. This shouldn't be an issue as most 3rd party patches are
-only needed for a very select group of users.
-
-Run the following commands to configure your kernel:
-
-
-
- * cd /usr/src/kernel/linux
-
- * make menuconfig
-
-
-Please note the following kernel prompts reflect a 2.4.14 kernel (with some
-of the optional Patch-O-Matic additions. Please read the following carefully
-for recommendations:
-
-+--------------------------------------------------------------------------------------------------+
-|[ Code maturity level options ] |
-| |
-| * Prompt for development and/or incomplete code/drivers (CONFIG_EXPERIMENTAL) [Y/n/?] |
-| - YES: though not required for IP MASQ, this option allows the kernel to create |
-| the MASQ modules and enable the option for port forwarding |
-| |
-| * Enable loadable module support (CONFIG_MODULES) [Y/n/?] |
-| - YES: allows you to load kernel IP MASQ modules |
-| |
-| * Set version information on all module symbols (CONFIG_MODVERSIONS) [Y/n/?] |
-| - YES: allows newer kernels to load older modules if possible |
-| |
-| * Kernel module loader (CONFIG_KMOD) [Y/n/?] |
-| - OPTIONAL: Recommended : allows the kernel to load various kernel modules as it needs them |
-| |
-| == Non-MASQ options skipped |
-| == (CPU type, memory, SMP, FPU, specific stuff) |
-| |
-| |
-|[ General setup ] |
-| |
-| * Networking support (CONFIG_NET) [Y/n/?] |
-| - YES: Enables the network subsystem |
-| |
-| == Non-MASQ options skipped |
-| == (specific hardware, PCI, kernel binaries, PCMCIA, etc.) |
-| |
-| |
-| * Sysctl support (CONFIG_SYSCTL) [Y/n/?] |
-| - YES: Enables the ability to enable disable options such as forwarding, |
-| dynamic IPs, etc. via the /proc interface |
-| |
-| |
-|[ Block devices ] |
-| |
-| == Non-MASQ options skipped |
-| == (kernel binaries, power management, PnP, RAID, etc.) |
-| |
-| == Don't forget to compile in support for hardware that you might need: |
-| == IDE controllers, HDs, CDROMs, etc. |
-| |
-|[ Networking options ] |
-| |
-| * Packet socket (CONFIG_PACKET) [Y/m/n/?] |
-| - YES: Though this is OPTIONAL, this recommended feature will allow you |
-| to use TCPDUMP to debug any problems with IP MASQ |
-| |
-| * Packet socket: mmapped IO (CONFIG_PACKET_MMAP) [N/y/?] y |
-| - YES: Speed up the packet protocol |
-| |
-| * Kernel/User netlink socket (CONFIG_NETLINK) [Y/n/?] |
-| - OPTIONAL: Recommended : this feature will allow the logging of |
-| advanced firewall issues such as routing messages, etc |
-| |
-| * Routing messages (CONFIG_RTNETLINK) [N/y/?] (NEW) y |
-| - OPTIONAL: Allows for support of advanced kernel routing messages |
-| if you enabled the CONFIG_NETLINK option |
-| |
-| * Netlink device emulation (CONFIG_NETLINK_DEV) [N/y/m/?] (NEW) |
-| - NO: This option does not have anything to do with packet firewall |
-| logging |
-| |
-| * Network packet filtering (replaces ipchains) (CONFIG_NETFILTER) [N/y/?] y |
-| - YES: Enable this option to let IPTABLES configure the TCP/IP subsection |
-| of the kernel. By enabling this, then you can turn on advanced |
-| routing mechanisms like IP Masq, packet filtering, etc. |
-| |
-| * Network packet filtering debugging (CONFIG_NETFILTER_DEBUG) [N/y/?] (NEW) n |
-| - NO: Not required for Masquerading functionality though it may help |
-| for troubleshooting. There might be a performance penalty when |
-| enabling this. |
-| |
-| * Socket Filtering (CONFIG_FILTER) [Y/n/?] |
-| - OPTIONAL: Recommended : Though this doesn't have anything do with IPMASQ, |
-| if you plan on implimenting a DHCP server on the internal network, you WILL |
-| need to enable this option. |
-| |
-| * Unix domain sockets (CONFIG_UNIX) [Y/m/n/?] |
-| - YES: This enables the UNIX TCP/IP sockets mechanisms |
-| |
-| * TCP/IP networking (CONFIG_INET) [Y/n/?] |
-| - YES: Enables the TCP/IP protocol |
-| |
-| * IP: multicasting (CONFIG_IP_MULTICAST) [N/y/?] |
-| - OPTIONAL: You can enable this if you want to be able to receive |
-| Multicast traffic. Please note that your ISP must |
-| support Multicast as well for this all to work at all |
-| |
-| * IP: advanced router (CONFIG_IP_ADVANCED_ROUTER) [Y/n/?] |
-| - OPTIONAL: Though there is nothing in this section mandatory for |
-| Masquerade, some specific options might be useful |
-| |
-| == Non-MASQ options skipped |
-| == ( autoconf, tunneling ) |
-| |
-| * IP: multicast routing (CONFIG_IP_MROUTE) [N/y/?] n |
-| - OPTIONAL: Though not needed for IPMASQ, enabling this feature will |
-| let you route multicast traffic through your Linux box. |
-| Please note that this requires that your ISP be multicast |
-| enabled as well. |
-| |
-| == Non-MASQ options skipped |
-| == (ARPd) |
-| |
-| * IP: TCP Explicit Congestion Notification support (CONFIG_INET_ECN) [N/y/?] n |
-| - NO: Though enabling this option would be great, there are many Internet |
-| sites out there that will block this. Hit the "?" when configuring |
-| the kernel to learn more about it but it is recommended to say NO for |
-| now. |
-| |
-| * IP: TCP syncookie support (disabled per default) (CONFIG_SYN_COOKIES) [Y/n/?] |
-| - YES: Recommended : for basic TCP/IP network security |
-| |
-| |
-|[ Networking options --> IP: Netfilter Configuration ] |
-| |
-| |
-| * Connection tracking (required for masq/NAT) (CONFIG_IP_NF_CONNTRACK) [N/y/m/?] (NEW) m |
-| - YES: (Module) This enables the kernel to track various network connections. |
-| This option is required for Masquerading support as well as to enable |
-| Stateful tracking for various filewall mechanisms. Please note that |
-| if you compile this directly into the kernel, you cannot enable |
-| the legacy IPCHAINS or IPFWADM compatibility modules. |
-| |
-| * FTP protocol support (CONFIG_IP_NF_FTP) [M/n/?] (NEW) m |
-| - YES: (Module) This enables the proper Masquerading of FTP connections if |
-| CONFIG_IP_NF_CONNTRACK was enabled above |
-| |
-| * IRC protocol support (CONFIG_IP_NF_IRC) [M/n/?] (NEW) m |
-| - YES: (Module) This enables the proper Masquerading of IRC connections if |
-| CONFIG_IP_NF_CONNTRACK was enabled above |
-| |
-| * Userspace queueing via NETLINK (EXPERIMENTAL) (CONFIG_IP_NF_QUEUE) [N/y/m/?] (NEW) m |
-| - OPTIONAL: Though this is OPTIONAL, this feature will allow IPTABLES to |
-| copy specific packets to UserSpace tools for additional checks |
-| |
-| * IP tables support (required for filtering/masq/NAT) (CONFIG_IP_NF_IPTABLES) [N/y/m/?] (NEW) m |
-| - YES: (Module) Enables IPTABLES support |
-| |
-| * limit match support (CONFIG_IP_NF_MATCH_LIMIT) [N/y/m/?] (NEW) y |
-| - OPTIONAL: (Module) Recommended : Though not required, this option can used to |
-| enable rate limiting of both traffic and loggin messages help slow down denial |
-| of service (DoS) attacks. |
-| |
-| * MAC address match support (CONFIG_IP_NF_MATCH_MAC) [N/y/m/?] (NEW) m |
-| - OPTIONAL: Though not required, the option can allow you to |
-| filter traffic based upon the SOURCE Ethernet MAC address. |
-| |
-| * netfilter MARK match support (CONFIG_IP_NF_MATCH_MARK) [N/y/m/?] (NEW) y |
-| - YES: (Module) Recommended : This enables IPTABLES to take action upon marked packets. |
-| This mechanism can allow for PORTFW functionality, TOS marking, etc. |
-| |
-| * Multiple port match support (CONFIG_IP_NF_MATCH_MULTIPORT) [N/y/m/?] (NEW) y |
-| - YES: (Module) Recommended : This enables IPTABLES to accept mutliple SRC/DST port |
-| ranges (non-contiguous) instead of one port range per IPTABLES |
-| statement. |
-| |
-| * TOS match support (CONFIG_IP_NF_MATCH_TOS) [Y/m/n/?] n |
-| - OPTIONAL: This allows IPTABLES to match packets based upon their |
-| DIFFSERV settings. |
-| |
-| * LENGTH match support (CONFIG_IP_NF_MATCH_LENGTH) [N/m/?] (NEW) n |
-| - OPTIONAL: This allows IPTABLES to match packets based upon their |
-| packet length. |
-| |
-| * TTL match support (CONFIG_IP_NF_MATCH_TTL) [N/m/?] (NEW) ? n |
-| - OPTIONAL: This allows IPTABLES to match packets based upon their |
-| TTL settings. |
-| |
-| * tcpmss match support (CONFIG_IP_NF_MATCH_TCPMSS) [N/y/m/?] m |
-| - OPTIONAL: (Module) Recommended : This option allows users to examine the MSS value in |
-| TCP SYN packets. This is an advanced knob but can be very valuable in |
-| troubleshooting MTU problems. |
-| |
-| * Connection state match support (CONFIG_IP_NF_MATCH_STATE) [M/n/?] m |
-| - YES: (Module) Recommended : This option allows for Stateful tracking of network |
-| connections. |
-| |
-| * Unclean match support (EXPERIMENTAL) (CONFIG_IP_NF_MATCH_UNCLEAN) [N/y/m/?] y |
-| - YES: (Module) Recommended : This option allows for connection tracking on odd packets. |
-| It cal also help in the detection of possibly malicious packets. |
-| This can be a valuable tool in tracking hostile people on the network. |
-| |
-| * Owner match support (EXPERIMENTAL) (CONFIG_IP_NF_MATCH_OWNER) [N/y/m/?] n |
-| - OPTIONAL: This option allows IPTABLES to match traffic based upon the |
-| user login, group, etc. who created the traffic. |
-| |
-| * Packet filtering (CONFIG_IP_NF_FILTER) [N/y/m/?] ? y |
-| - YES: (Module) This option allows for the kernel to be able filter traffic at |
-| the INPUT, FORWARDING, and OUTPUT traffic points. |
-| |
-| * REJECT target support (CONFIG_IP_NF_TARGET_REJECT) [N/y/m/?] (NEW) y |
-| - YES: (Module) With this option, a packet firewall can send an ICMP Reject packet |
-| back to the originator when a packet is blocked. |
-| |
-| * MIRROR target support (EXPERIMENTAL) (CONFIG_IP_NF_TARGET_MIRROR) [N/y/m/?] (NEW) n |
-| - OPTIONAL: This option allows the packet firewall to mirror the exact same |
-| network packet back to the originator when it is supposed to be |
-| blocked. This is similar to the REJECT option above but it actually |
-| sends the original packet back to the originator. i.e. a |
-| hostile user could actually portscan themselves. |
-| |
-| |
-| * Full NAT (CONFIG_IP_NF_NAT) [M/n/?] m |
-| - YES: (Module) This option enables the future menus to enable Masquerading, |
-| PORTFWing, Full (1:1) NAT, etc. |
-| |
-| |
-| * MASQUERADE target support (CONFIG_IP_NF_TARGET_MASQUERADE) [M/n/?] (NEW) m |
-| - YES: (Module) This option specifically enables Masquerade into the |
-| kernel |
-| |
-| * REDIRECT target support (CONFIG_IP_NF_TARGET_REDIRECT) [N/y/m/?] n |
-| - OPTIONAL: Not needed for normal MASQ functionality though people who |
-| want to do transparent proxy via Squid will want this. |
-| |
-| * Basic SNMP-ALG support (EXPERIMENTAL) (CONFIG_IP_NF_NAT_SNMP_BASIC) [N/m/?] n |
-| - OPTIONAL: This enables IPTABLES to properly NAT internal SNMP packets so |
-| that machines with duplicate addressing ranges can be properly |
-| managed. |
-| |
-| |
-| * Packet mangling (CONFIG_IP_NF_MANGLE) [N/y/m/?] y |
-| - YES: (Module) This option allows for advanced IPTABLES packet manipulation |
-| options. |
-| |
-| |
-| * TOS target support (CONFIG_IP_NF_TARGET_TOS) [N/y/m/?] (NEW) n |
-| - OPTIONAL: Enables the kernel to modify the TOS field in a packet |
-| before routing it on |
-| |
-| * MARK target support (CONFIG_IP_NF_TARGET_MARK) [N/y/m/?] (NEW) m |
-| - OPTIONAL: (Module) Recommended : This enables the kernel to manipulate |
-| packets based upon the MARK field. This can be used for PORTFW |
-| as well as many other things. |
-| |
-| * LOG target support (CONFIG_IP_NF_TARGET_LOG) [N/y/m/?] m |
-| - YES: (Module) This allows for the logging of packets before they are accepted, |
-| denied, rejected, etc. |
-| |
-| * TCPMSS target support (CONFIG_IP_NF_TARGET_TCPMSS) [N/y/m/?] ? m |
-| - YES: (Module) This option help some people with MTU problems. Typically, |
-| most users have to set their Internet connection's MTU to |
-| 1500 as well as ALL internal machines to 1500. With this |
-| option, this whole MTU issue might be finally solved. |
-| |
-| * ipchains (2.2-style) support (CONFIG_IP_NF_COMPAT_IPCHAINS) [N/y/m/?] m |
-| - OPTIONAL: (Module) Recommended : If you have an existing IPCHAINS ruleset |
-| (2.2.x kernels) and enable this option, you can continue to use the |
-| IPCHAINS program and the majority of your old ruleset except for the |
-| use of any 2.2.x kernel-specific modules. Please note that if this |
-| IPCHAINS module is loaded, ALL IPTABLES modules will be non- |
-| operational. This is an either/or deal only intended for legacy |
-| rulesets. |
-| |
-| * ipfwadm (2.0-style) support (CONFIG_IP_NF_COMPAT_IPFWADM) [N/y/m/?] n |
-| - OPTIONAL: If you have an existing IPFWADM ruleset (2.0.x kernels) and |
-| enable this option, you can continue to use the IPFWADM program and |
-| the majority of your old ruleset except for the use of any 2.0.x |
-| kernel-specific modules. Please note that if this IPFWADM module |
-| is loaded, ALL IPTABLES modules will be non operational. This is |
-| an either/or deal only intended to support legacy rulesets. |
-| |
-| |
-| == Non-MASQ options skipped |
-| == (IPv6, khttpd, ATM, IPX, AppleTalk, etc.) -- |
-| |
-| * Fast switching (read help!) (CONFIG_NET_FASTROUTE) [N/y/?] n |
-| - NO: This performance optimization is NOT compatible with IP MASQ and/or |
-| packet filtering |
-| |
-| |
-| == Non-MASQ options skipped |
-| == (QoS, Telephony, IDE, SCSI, 1394FW, I2O, etc) |
-| |
-| == Don't forget to compile in support for hardware that you might need: |
-| == IDE: HDs, CDROMs, etc. |
-| == SCSI: HDs, CDROMs, etc. |
-| |
-| |
-|[ Network device support ] |
-| |
-| * Network device support (CONFIG_NETDEVICES) [Y/n/?] |
-| - YES: Enables the Linux Network device sublayer |
-| |
-| == Non-MASQ options skipped |
-| == (Arcnet) |
-| |
-| |
-| * Dummy net driver support (CONFIG_DUMMY) [M/n/y/?] |
-| - YES: Though OPTIONAL, this option can help when debugging problems |
-| |
-| == Non-MASQ options skipped |
-| == (EQL, etc..) |
-| |
-| == Don't forget to compile in support for hardware that you might need: |
-| == NICs: eth, tr, etc. |
-| == MODEMs: ppp (ppp async) and/or slip |
-| == WANs: T1, T3, ISDN, etc. |
-| == ISDN: for internal ISDN modems |
-| |
-| |
-| == Non-MASQ options skipped |
-| == (Amateur Radio, IrDA, ISDN, USB, etc.) |
-| |
-| |
-|[ Character devices ] |
-| |
-| == Don't forget to compile in serial port support if you are a modem user |
-| == Don't forget to compile in mouse support |
-| |
-| == Non-MASQ options skipped |
-| == (I2C, Watchdog cards, Ftape, Video for Linux, etc. ) |
-| |
-| |
-|[ File systems ] |
-| |
-| == Non-MASQ options skipped |
-| == (Quota, ISO9660, NTFS, etc ) |
-| |
-| * /proc filesystem support (CONFIG_PROC_FS) [Y/n/?] |
-| - YES: Required to dynamically configure the Linux forwarding |
-| and NATing systems |
-| |
-| |
-| == Non-MASQ options skipped |
-| == (Console drivers, Sound, USB, Kernel Hacking) |
-+--------------------------------------------------------------------------------------------------+
-So go ahead and select "exit" and you should be prompted to save your config.
-
-NOTE: These are just the kernel components you need for IP Masquerade
-networking support. You will need to select whatever other options needed for
-your specific setup. If you want more information on what each one of these
-kernel modules does, please see the FAQ section of this HOWTO for details.
-
- * Now compile the kernel (make dep; make clean; make bzImage; make modules;
- make modules_install) , etc. Again, it is beyond the scope of this HOWTO
- if you have problems compiling your kernel. Please see Section 2.6 for
- URLs to the KERNEL howto, etc.
-
- * You will then have move over the kernel binary, update your bootloader
- (LILO, Grub, etc.), and reboot. If you have questions about kernel
- compiling, I highly recommend to consult some of the URLs mentioned above
- in this section.
-
-
------------------------------------------------------------------------------
-3.2.2. Compiling Linux 2.2.x Kernels
-
-Please see Section 2.7 for any required software, patches, etc.
-
- * First of all, you need the kernel source for 2.2.x (preferably the latest
- kernel version)
-
- + NOTE #1: --- UPDATE YOUR KERNEL --- Linux 2.2.x kernels less than
- version 2.2.20 contain several different security vulnerabilities
- (some were MASQ specific). Kernels less than 2.2.20 have a few local
- vulnerabilities. Kernel versions less than 2.2.16 have a TCP root
- exploit vulnerability and versions less than 2.2.11 have a IPCHAINS
- fragmentation bug. Because of these issues, users running a firewall
- with strong IPCHAINS rulesets are open to possible instrusion. Please
- upgrade your kernel to a fixed version.
-
- + NOTE #2: As the 2.2.x train progressed, the compile-time options keep
- on changing. As of this version, this section reflects the settings
- for a 2.2.20 kernel.
-
- If you are running either a newer or older kernel version, the
- dialogs will look different. It is recommended that you update to the
- newest kernel for added capability and stability of the system.
-
-
- * If this is your first time compiling the kernel, don't be scared. In
- fact, it's rather easy and it's covered in several URLs found in Section
- 2.7. Please note that the instructions included here is just one way to
- do build a kernel. Please see the Kernel HOWTO for full details.
-
- NOTE: Please notice that it isn't recommended to put the new kernel
- sources into /usr/src/linux. You should leave the original kernel sources
- that came with your Linux distribution in /usr/src/linux. For more
- details on this topic, please read the "README" file in the top level
- directory of your kernel sources.
-
- * For this HOWTO example, create a directory called /usr/src/kernel. Next,
- "cd" into this directory and download the newest 2.2.x kernel sources
- into it. Once downloaded, issue the following command (if the file ends
- in a .tar.gz): tar xvzf linux-2.2.x.tar.gz or (if the file ends in a
- .tar.bzip2): tar xyvf linux-2.2.x.tar.bz2. Please substitute the "x" in
- the 2.2.x filename with the Linux 2.2 kernel version you downloaded.
-
- NOTE: Some Linux distributions use the "I" option instead of the "y"
- option to decompress bzip2 archives.
-
- Once uncompressed, I recommend that you rename the directory from "linux"
- to "linux-2.2.x" for clarity. To do this, run the command mv linux
- linux-2.2.x. Next, make sure there is a directory or symbolic link
- pointing to /usr/src/kernel/linux ie. run the command: ln -s /usr/src/
- kernel/linux-2.2.x /usr/src/kernel/linuxo again subsituting the "x" for
- your proper kernel version.
-
- * Apply any appropriate or optional patches to the kernel source code. By
- default, stock Linux kernels do not require any specific patching in
- order for the system to work. Features like PPTP/IPSEC masqurading are
- already built-in in the newest kernels but other tools like Xwindows
- forwarders are optional. Please refer to Section 2.7 for URLs and the
- [http://ipmasq.webhop.net/] IP Masquerade Resources for up-to-date
- information and patch URLs.
-
- * Now that the kernel is patched up (if required), here are the MINIMUM
- kernel configuration options required to enable IP Masquerade
- functionality. Please understand that this HOWTO illustrates just ONE way
- to compile a kernel. The main difference from this method vs. a different
- one is some people wish to compile things either as modules OR
- monolithically right into the kernel. Basically, compiling things as
- modules gives you added flexibility to what is or isn't installed into
- the kernel (reduces unneeded memory use and allow for drop-in upgrades
- [no need to reboot]) BUT they add more complexity to your configuration.
- On the flip side, compiling things directly into the kernel makes things
- simpler BUT you loose a level of flexibility. The following example is a
- mixture of both built-in AND modules.
-
- Side Note: It is assumed that you will also configure the kernel to use
- your other installed hardware such as network interfaces, optional SCSI
- controllers, etc. as well. Please refer to the Linux Kernel HOWTO and the
- kernel source's README file and Documentation/ directory for detailed
- help on compiling a kernel.
-
-
-Please note the YES or NO ANSWERS to the following. Not all options will be
-available without the proper kernel patches described later in this HOWTO.
-
-Run the following commands to configure your kernel:
-
- * cd /usr/src/kernel/linux
-
- * make menuconfig
-
-
-
-
-The following kernel prompts reflect a 2.2.20 kernel:
-
-+------------------------------------------------------------------------------------------------+
-|[ Code maturity level options ] |
-| |
-| * Prompt for development and/or incomplete code/drivers (CONFIG_EXPERIMENTAL) [Y/n/?] |
-| - YES: though not entirely required for IP MASQ, this option allows the kernel |
-| to create possible additional MASQ modules such as PORTFW, etc. |
-| |
-| == Non-MASQ options skipped |
-| == (CPU, memory, MTRR, SMP, etc.) |
-| |
-| |
-|[ Loadable module support ] |
-| |
-| * Enable loadable module support (CONFIG_MODULES) [Y/n/?] y |
-| - YES: allows you to load kernel IP MASQ modules |
-| |
-| * Set version information on all symbols for modules (CONFIG_MODVERSIONS) [N/y/?] y |
-| - YES: allows newer kernels to load older modules if possible |
-| |
-| * Kernel module loader (CONFIG_KMOD) [Y/n/?] y |
-| - OPTIONAL: Recommended : allows the kernel to load various kernel modules as |
-| it needs them |
-| |
-| |
-|[ General setup ] |
-| |
-| * Networking support (CONFIG_NET) [Y/n/?] |
-| - YES: This enables the network subsystem |
-| |
-| == Non-MASQ options skipped |
-| == (PCI, kernel binaries, specific hardware options, etc.) |
-| |
-| |
-| * Sysctl support (CONFIG_SYSCTL) [Y/n/?] |
-| - YES: Enables the ability to enable disable options such as forwarding, |
-| dynamic IPs, etc. via the /proc interface |
-| |
-| |
-|[ Block devices ] |
-| |
-| == Non-MASQ options skipped |
-| == (kernel binaries, power management, PnP, IDE, SCSI, etc.) |
-| |
-| == Don't forget to compile in support for hardware that you might need: |
-| == IDE controllers, HDs, CDROMs, etc. |
-| |
-| |
-|[ Networking options ] |
-| |
-| |
-| * Packet socket (CONFIG_PACKET) [Y/m/n/?] y |
-| - YES: Though this is OPTIONAL, this recommended feature will allow you |
-| to use TCPDUMP to debug any problems with IP MASQ |
-| |
-| * Kernel/User netlink socket (CONFIG_NETLINK) [Y/n/?] y |
-| - OPTIONAL: Recommended : This feature will allow the logging of |
-| advanced firewall issues such as routing messages, etc |
-| |
-| * Routing messages (CONFIG_RTNETLINK) [Y/n/?] y |
-| - OPTIONAL: If you enabled the CONFIG_NETLINK option above, this option |
-| will send routing messages and other information to SYSLOG. |
-| |
-| * Netlink device emulation (CONFIG_NETLINK_DEV) [N/y/m/?] (NEW) n |
-| - NO: This option does not have anything to do with packet firewall |
-| logging |
-| |
-| * Network firewalls (CONFIG_FIREWALL) [Y/n/?] y |
-| - YES: Enables the kernel to be comfigured by the IPCHAINS firewall tool |
-| |
-| * Socket Filtering (CONFIG_FILTER) [Y/n/?] y |
-| - OPTIONAL: Though this doesn't have anything do with IPMASQ, if you |
-| plan on implimenting a DHCP server on the internal network, you |
-| WILL need this option. |
-| |
-| * Unix domain sockets (CONFIG_UNIX) [Y/m/n/?] y |
-| - YES: This enables the UNIX TCP/IP sockets mechanisms |
-| |
-| * TCP/IP networking (CONFIG_INET) [Y/n/?] y |
-| - YES: Enables the TCP/IP protocol |
-| |
-| * IP: multicasting (CONFIG_IP_MULTICAST) [N/y/?] y |
-| - OPTIONAL: You can enable this if you want to be able to receive |
-| Multicast traffic. Please note that your ISP must |
-| support Multicast as well for this all to work |
-| |
-| * IP: advanced router (CONFIG_IP_ADVANCED_ROUTER) [Y/n/?] n |
-| - OPTIONAL: Though there is nothing in this section mandatory for |
-| Masquerade, some specific options might be useful |
-| |
-| * IP: kernel level autoconfiguration (CONFIG_IP_PNP) [N/y/?] ? |
-| - NO: Not needed for normal MASQ functionality |
-| |
-| * IP: firewalling (CONFIG_IP_FIREWALL) [Y/n/?] y |
-| - YES: This enables the kernel to support packet filtering, NAT, etc. |
-| |
-| * IP: firewall packet netlink device (CONFIG_IP_FIREWALL_NETLINK) [Y/n/?] n |
-| - OPTIONAL: Though this is OPTIONAL, this feature will allow IPCHAINS to |
-| copy some packets to UserSpace tools for additional checks |
-| |
-| * IP: transparent proxy support (CONFIG_IP_TRANSPARENT_PROXY) [N/y/?] n |
-| - OPTIONAL: Not needed for normal MASQ functionality though people who |
-| want to do transparent proxy via Squid will want this. Please note |
-| that there is a PERFORMANCE PENALTY enabling this feature. |
-| |
-| * IP: masquerading (CONFIG_IP_MASQUERADE) [Y/n/?] y |
-| - YES: Enable IP Masquerade to re-address specific internal to external |
-| TCP/IP packets |
-| |
-| * IP: ICMP masquerading (CONFIG_IP_MASQUERADE_ICMP) [Y/n/?] y |
-| - YES: Enable support for masquerading ICMP ping packets (ICMP error |
-| codes will be MASQed regardless). This is an important feature |
-| for troubleshooting connections. |
-| |
-| * IP: masquerading special modules support (CONFIG_IP_MASQUERADE_MOD) [Y/n/?] y |
-| - YES: Though OPTIONAL, this enables the option to later enable other |
-| modules like the PORTFW to give external computers a directly |
-| connection to specified internal MASQed machines. |
-| |
-| * IP: ipautofw masq support (EXPERIMENTAL) (CONFIG_IP_MASQUERADE_IPAUTOFW) [N/y/m/?] n |
-| - NO: NOT recommended : IPautofw is a legacy method of port forwarding. It |
-| is mainly old code and has been found to have some issues. |
-| |
-| * IP: ipportfw masq support (EXPERIMENTAL) (CONFIG_IP_MASQUERADE_IPPORTFW) [Y/m/n/?] y |
-| - OPTIONAL: Recommended : This enables PORTFW which allows external computers |
-| on the Internet to directly communicate to specified internal MASQed |
-| machines. This feature is typically used to allow access to internal |
-| SMTP, TELNET, and WWW servers. Please note that FTP port forwarding |
-| needs an additional patch, as described in the FAQ section of the MASQ |
-| HOWTO. Please see the this FAQ section in the HOWTO for additional |
-| information. |
-| |
-| * IP: ip fwmark masq-forwarding support (EXPERIMENTAL) (CONFIG_IP_MASQUERADE_MFW) [Y/m/n/?] y |
-| - OPTIONAL: This is a NEW method of performing PORTFW-like functionality which is |
-| similar to how the new 2.4.x kernels do things. With this option, IPCHAINS |
-| can mark packets that should have additional work done upon it. Using a |
-| UserSpace tool, much like IPMASQADM or IPPORFW, IPCHAINS would then |
-| do things like re-address the packets, change their TOS value, etc. |
-| Currently, this code is less tested than PORTFW but it looks promising. |
-| For now, this HOWTO recommends to use IPMASQADM and IPPORTFW. If you |
-| have specific thoughts or comments on MFW, please email dranch. |
-| |
-| * IP: optimize as a router not host (CONFIG_IP_ROUTER) [Y/n/?] y |
-| - YES: This optimizes the kernel for the network subsystem, though it |
-| isn't well known if this makes a siginificant performance difference |
-| or not. |
-| |
-| == Non-MASQ options skipped |
-| == ( autoconf, tunneling, GRE ) |
-| |
-| |
-| * IP: multicast routing (CONFIG_IP_MROUTE) [N/y/?] n |
-| - OPTIONAL: Though not needed for IPMASQ, enabling this feature will |
-| let you route multicast traffic through your Linux box. |
-| Please note that this requires that your ISP be multicast |
-| enabled as well. |
-| |
-| |
-| == Non-MASQ options skipped |
-| == (Aliasing, ARPd) |
-| |
-| * IP: TCP syncookie support (disabled per default) (CONFIG_SYN_COOKIES) [Y/n/?] |
-| - YES: Recommended : for basic TCP/IP network security |
-| |
-| * IP: GRE tunnels over IP (CONFIG_NET_IPGRE) [N/y/m/?] |
-| - NO: This OPTIONAL selection is to enable PPTP and GRE tunnels through |
-| the IP MASQ box |
-| |
-| == Non-MASQ options skipped |
-| == (aliasing, ARPd) |
-| |
-| |
-| * IP: TCP syncookie support (not enabled per default) (CONFIG_SYN_COOKIES) [Y/n/?] |
-| - YES: HIGHLY recommended for basic TCP/IP network security |
-| |
-| == Non-MASQ options skipped |
-| == (RARP) |
-| |
-| |
-| * IP: Allow large windows (not recommended if <16Mb of memory) * (CONFIG_SKB_LARGE) [Y/n/?] |
-| - YES: This is recommended to optimize Linux's TCP window |
-| |
-| == Non-MASQ options skipped |
-| == (IPv6, IPX, WAN router, etc.) |
-| |
-| * Fast switching (read help!) (CONFIG_NET_FASTROUTE) [N/y/?] n |
-| - NO: This performance optimization is NOT compatible with IP MASQ and/or |
-| packet filtering |
-| |
-| |
-| == Non-MASQ options skipped |
-| == (Slow CPU, Telephony, SCSI, I2O, etc. ) |
-| |
-| == Don't forget to compile in support for hardware that you might need: |
-| == SCSI: HDs, CDROMs, etc. |
-| |
-| |
-|[ Network device support ] |
-| |
-| * Network device support (CONFIG_NETDEVICES) [Y/n/?] |
-| - YES: Enables the Linux Network device sublayer |
-| |
-| |
-| == Non-MASQ options skipped |
-| == (Arcnet) |
-| |
-| |
-| * Dummy net driver support (CONFIG_DUMMY) [M/n/y/?] |
-| - YES: Though OPTIONAL, this option can help when debugging problems |
-| |
-| |
-| == Non-MASQ options skipped |
-| == (EQL, NICs, Wireless, IrDA, ISDN, etc..) |
-| |
-| == Don't forget to compile in support for hardware that you might need: |
-| == NICs: eth, tr, etc. |
-| == MODEMs: ppp and/or slip |
-| == WANs: T1, T3, ISDN, etc. |
-| == ISDN: for internal ISDN modems |
-| |
-| |
-| [ Character devices ] |
-| |
-| == Don't forget to compile in serial port support for modem users |
-| == Don't forget to compile in mouse support |
-| |
-| |
-| == Non-MASQ options skipped |
-| == (I2C, Watchdog cards, Ftape, Video for Linux, USB, etc. ) |
-| |
-| |
-|[ File systems ] |
-| |
-| == Non-MASQ options skipped |
-| == (Quota, ISO9660, NTFS, etc ) |
-| |
-| |
-| * /proc filesystem support (CONFIG_PROC_FS) [Y/n/?] |
-| - YES: Required to dynamically configure the Linux forwarding |
-| and NATing systems |
-| |
-| |
-| == Non-MASQ options skipped |
-| == (network fs, NLS, video section, sound, kernel hacking) |
-+------------------------------------------------------------------------------------------------+
-So go ahead and "exit" and you should be prompted to save your config.
-
-NOTE: These are just the components you need for IP Masquerade. You will need
-to select whatever other options needed for your specific setup.
-
- * Now compile the kernel (make dep; make clean; make bzImage; make modules;
- make modules_install) , etc. Again, it is beyond the scope of this HOWTO
- if you have problems compiling your kernel. Please see Section 2.7 for
- URLs to the KERNEL howto, etc.
-
- * You will then have move over the kernel binary, update your bootloader
- (LILO, Grub, etc.), and reboot. If you have questions about kernel
- compiling, I highly recommend to consult some of the URLs above in this
- section.
-
-
------------------------------------------------------------------------------
-3.2.3. Compiling Linux 2.0.x Kernels
-
-Please see Section 2.8 for any required software, patches, etc.
-
- * First of all, you need the kernel source for 2.0.x (preferably the latest
- kernel version)
-
- + As the 2.0.x train progress, the compile-time options keep on
- changing. As of this version, this section reflects the settings for
- a 2.0.39 kernel.
-
-
- * If this is your first time compiling the kernel, don't be scared. In
- fact, it's rather easy and it's covered in several URLs found in Section
- 2.8. Please note that the instructions included here is just one way to
- do build a kernel. Please see the Kernel HOWTO for full details.
-
- NOTE: Please notice that it isn't recommended to put the new kernel
- sources into /usr/src/linux. You should leave the original kernel sources
- that came with your Linux distribution in /usr/src/linux. For more
- details on this topic, please read the "README" file in the top level
- directory of your kernel sources.
-
- * For this HOWTO example, create a directory called /usr/src/kernel. Next,
- "cd" into this directory and download the newest 2.0.x kernel sources
- into it. Once downloaded, issue the following command: tar xvzf
- linux-2.0.x.tar.gz . Please substitute the "x" in the 2.0.x filename with
- the Linux 2.0 kernel version you downloaded.
-
- Once uncompressed, I recommend that you rename the directory from "linux"
- to "linux-2.0.x" for clarity. To do this, run the command mv linux
- linux-2.0.x. Next, make sure there is a directory or symbolic link
- pointing to /usr/src/kernel/linux ie. run the command: ln -s /usr/src/
- kernel/linux-2.0.x /usr/src/kernel/linuxo again subsituting the "x" for
- your proper kernel version.
-
- * Apply any appropriate or optional patches to the kernel source code. By
- default, stock Linux kernels do not require any specific patching in
- order for the system to work. Features like IPPORTFW, PPTP, and Xwindows
- forwarders are optional but very useful. Please refer to Section 2.8 for
- URLs and the [http://ipmasq.webhop.net/] IP Masquerade Resources for
- up-to-date information and patch URLs.
-
- * Now that the kernel is patched up (if required), here are the MINIMUM
- kernel configuration options required to enable IP Masquerade
- functionality. Please understand that this HOWTO illustrates just ONE way
- to compile a kernel. The main difference from this method vs. a different
- one is some people wish to compile things either as modules OR
- monolithically right into the kernel. Basically, compiling things as
- modules gives you added flexibility to what is or isn't installed into
- the kernel (reduces unneeded memory use and allow for drop-in upgrades
- [no need to reboot]) BUT they add more complexity to your configuration.
- On the flip side, compiling things directly into the kernel makes things
- simpler BUT you loose a level of flexibility. The following example is a
- mixture of both built-in AND modules.
-
- Side Note: It is assumed that you will also configure the kernel to use
- your other installed hardware such as network interfaces, optional SCSI
- controllers, etc. as well. Please refer to the Linux Kernel HOWTO and the
- kernel source's "README" file and "Documentation/" directory for detailed
- help on compiling a kernel.
-
-
-Please note the YES or NO ANSWERS to the following options. Not all options
-will be available without the proper kernel patches described later in this
-HOWTO:
-
-Run the following commands to configure your kernel:
-
- * cd /usr/src/kernel/linux
-
- * make menuconfig
-
-
-The following kernel prompts reflect a 2.0.39 kernel:
-
-+--------------------------------------------------------------------------------------------------+
-|[ Code maturity level options ] |
-| |
-| * Prompt for development and/or incomplete code/drivers (CONFIG_EXPERIMENTAL) [Y/n/?] |
-| - YES: this will allow you to later select the IP Masquerade feature code |
-| |
-| |
-|[ Loadable module support ] |
-| |
-| * Enable loadable module support (CONFIG_MODULES) [Y/n/?] y |
-| - YES: allows you to load kernel IP MASQ modules |
-| |
-| * Set version information on all module symbols (CONFIG_MODVERSIONS) [N/y/?] y |
-| - YES: allows newer kernels to load older modules if possible |
-| |
-| * Kernel daemon support (e.g. autoload of modules) (CONFIG_KERNELD) [N/y/?] y |
-| - OPTIONAL: Recommended : allows the kernel to load various kernel modules as |
-| it needs them |
-| |
-| |
-|[ General setup ] |
-| |
-| == Non-MASQ options skipped |
-| == (FPU, memory) |
-| |
-| * Networking support (CONFIG_NET) [Y/n/?] y |
-| - YES: Enables the network subsystem |
-| |
-| == Non-MASQ options skipped |
-| == (memory, PCI, binary format, APM, etc.) |
-| |
-| == Don't forget to compile in support for hardware that you might need: |
-| == IDE controllers, HDs, CDROMs, etc. |
-| |
-| |
-|[ Networking options ] |
-| |
-| * Network firewalls (CONFIG_FIREWALL) [Y/n/?] y |
-| - YES: Enables the IPFWADM firewall tool |
-| |
-| == Non-MASQ options skipped |
-| == (Aliasing) |
-| |
-| |
-| * TCP/IP networking (CONFIG_INET) [Y/n/?] y |
-| - YES: Enables the TCP/IP protocol |
-| |
-| * IP: forwarding/gatewaying (CONFIG_IP_FORWARD) [N/y/?] y |
-| - YES: Enables Linux network packet forwarding and routing |
-| - Controlled by IPFWADM |
-| |
-| * IP: multicasting (CONFIG_IP_MULTICAST) [N/y/?] y |
-| - OPTIONAL: You can enable this if you want to be able to receive |
-| Multicast traffic. Please note that your ISP must |
-| support Multicast as well for this all to work |
-| |
-| * IP: syn cookies (CONFIG_SYN_COOKIES) [Y/n/?] y |
-| - YES: HIGHLY recommended for basic network security |
-| |
-| * IP: firewalling (CONFIG_IP_FIREWALL) [Y/n/?] y |
-| - YES: Enable the packet firewall features |
-| |
-| * IP: firewall packet logging (CONFIG_IP_FIREWALL_VERBOSE) [Y/n/?] y |
-| - YES: Allows the kernel to report back on various packets traversing |
-| the firewall. |
-| |
-| * IP: masquerading (CONFIG_IP_MASQUERADE [Y/n/?] y |
-| - YES: Enable the kernel to perform IP MASQ NAT functionality |
-| |
-| * IP: ipautofw masquerade support (EXPERIMENTAL) (CONFIG_IP_MASQUERADE_IPAUTOFW) [Y/n/?] n |
-| - NO: NOT Recommended : IPautofw is a legacy method of TCP/IP port forwarding. |
-| Though IPautofw works, IPPORTFW is a better choice. |
-| |
-| |
-| * IP: ipportfw masq support (EXPERIMENTAL) (CONFIG_IP_MASQUERADE_IPPORTFW) [Y/n/?] y |
-| - YES: This option is ONLY AVAILABLE VIA A PATCH for the 2.0.x kernels. |
-| With this option, external computers on the Internet can directly |
-| communicate to specified internal MASQed machines. This feature is |
-| typically used to access internal SMTP, TELNET, and WWW servers. |
-| FTP port forwarding sometimes might require an additional patch as |
-| described in the FAQ section. Additional information on port |
-| forwarding is available in the Forwards section of this HOWTO. |
-| |
-| |
-| * IP: MS PPTP masq support (EXPERIMENTAL) (CONFIG_IP_MASQUERADE_PPTP) [N/y/?] (NEW) n |
-| - OPTIONAL: Enabling this feature will allow internal MASQ clients to |
-| properly connect to PPTP servers on the Internet. |
-| |
-| * IP: MS PPTP Call ID masq support (CONFIG_IP_MASQUERADE_PPTP_MULTICLIENT) [N/y/?] (NEW) n |
-| - OPTIONAL: If you enabled the CONFIG_IP_MASQUERADE_PPTP above, this |
-| option will allow for multiple internal PPTP clients behind the MASQ |
-| server to communicate to the same PPTP server. |
-| |
-| * IP: MS PPTP masq debugging (DEBUG_IP_MASQUERADE_PPTP) [N/y/?] n |
-| - OPTIONAL: NOT recommended : This is not required for IP MASQ or MASQing PPTP |
-| connections unless you need additional troubleshooting help. If enabled, |
-| this can fill up your logs quickly. |
-| |
-| * IP: MS PPTP masq verbose debugging (DEBUG_IP_MASQUERADE_PPTP_VERBOSE) [N/y/?] (NEW) n |
-| - OPTIONAL: NOT Recommended : If you enabled the DEBUG_IP_MASQUERADE_PPTP |
-| option above, this will make the logging even more verbose. |
-| |
-| * IP: IPSEC ESP & ISAKMP masq support (EXPERIMENTAL) * (CONFIG_IP_MASQUERADE_IPSEC) [N/y/?] m |
-| - OPTIONAL: This option allows for some forms of IPSEC tunnels to be |
-| masquraded |
-| |
-| * IP: IPSEC masq table lifetime (minutes) (CONFIG_IP_MASQUERADE_IPSEC_EXPIRE) * [30] (NEW) |
-| - OPTIONAL: This feature allows to change the MASQ table timeouts so that |
-| idle IPSEC tunnels won't be prematurely disconnected. |
-| |
-| * IP: Disable inbound ESP destination guessing * (CONFIG_IP_MASQUERADE_IPSEC_NOGUESS) [N/y/?] n |
-| - OPTIONAL: This feature allows the kernel to guess where the fully encrypted IPSEC VPN |
-| might be going and add it to the MASQ table. |
-| |
-| * IP: IPSEC masq debugging (DEBUG_IP_MASQUERADE_IPSEC) [N/y/?] ? n |
-| - OPTIONAL: NOT recommended : This is not required for IP MASQ or MASQing IPSEC |
-| connections unless you need additional troubleshooting help. If enabled, |
-| this can fill up your logs quickly. |
-| |
-| * IP: IPSEC masq verbose debugging (DEBUG_IP_MASQUERADE_IPSEC_VERBOSE) [N/y/?] (NEW) n |
-| - OPTIONAL: NOT Recommended : If you enabled the DEBUG_IP_MASQUERADE_IPSEC |
-| option above, this will make the logging even more verbose. |
-| |
-| |
-| * IP: ICMP masquerading (CONFIG_IP_MASQUERADE_ICMP) [Y/n/?] |
-| - YES: Enable support for masquerading ICMP packets. Though thought of as |
-| optional, many programs will NOT function properly with out ICMP |
-| support. |
-| |
-| * IP: transparent proxy support (EXPERIMENTAL) (CONFIG_IP_TRANSPARENT_PROXY) [N/y/?] n |
-| - OPTIONAL: Not needed for normal MASQ functionality though people who |
-| want to do transparent proxy via Squid will want this. Please note |
-| that there is a PERFORMANCE PENALTY enabling this feature. |
-| |
-| * IP: loose UDP port managing (EXPERIMENTAL) (CONFIG_IP_MASQ_LOOSE_UDP) [Y/n/?] |
-| - YES: This option is ONLY AVAILABLE VIA A PATCH for the 2.0.x kernels. |
-| With this option, internally masqueraded computers can play |
-| NAT-friendly games over the Internet. Explicit details are given |
-| in the FAQ section of this HOWTO. |
-| |
-| * IP: always defragment (CONFIG_IP_ALWAYS_DEFRAG) [Y/n/?] |
-| - YES: This feature optimizes IP MASQ connections |
-| |
-| == Non-MASQ options skipped |
-| == (Accounting) |
-| |
-| |
-| * IP: optimize as router not host (CONFIG_IP_ROUTER) [Y/n/?] |
-| - YES: This optimizes the kernel for the network subsystem |
-| |
-| == Non-MASQ options skipped |
-| == (Tunneling, Mcast routing, RARP, PMTU, etc.) |
-| |
-| |
-| * IP: Drop source routed frames (CONFIG_IP_NOSR) [Y/n/?] |
-| - YES: HIGHLY recommended for basic network security |
-| |
-| == Non-MASQ options skipped |
-| == (IPX, Bridging, SCSI, etc.) |
-| |
-| == Don't forget to compile in support for hardware that you might need: |
-| == SCSI controllers, HDs, CDROMs, etc. |
-| |
-| |
-|[ Network device support ] |
-| |
-| * Network device support (CONFIG_NETDEVICES) [Y/n/?] |
-| - YES: Enables the Linux Network device sublayer |
-| |
-| |
-| == Non-MASQ options skipped |
-| == (Dummy, EQL, PPP, SLIP, NICs, Wireless, etc.) |
-| |
-| == Don't forget to compile in support for hardware that you might need: |
-| == NICs: eth, tr, etc. |
-| == MODEMs: ppp and/or slip |
-| == WANs: T1, T3, ISDN, etc. |
-| == ISDN: for internal ISDN modems |
-| |
-| |
-|[ File systems ] |
-| |
-| == Non-MASQ options skipped |
-| == (Quota, ISO9660, Codepages, NTFS, etc ) |
-| |
-| |
-| * /proc filesystem support (CONFIG_PROC_FS) [Y/n/?] |
-| - YES: Required to dynamically configure the Linux forwarding |
-| and NATing systems |
-| |
-| |
-| [ Character devices ] |
-| |
-| == Non-MASQ options skipped |
-| == (multi-port serial, parallel, mice, Ftape, Sound, etc. ) |
-| |
-| == Don't forget to compile in serial port support for modem users |
-| == Don't forget to compile in mouse support |
-| |
-+--------------------------------------------------------------------------------------------------+
-
-So go ahead and "exit" and you should be prompted to save your config.
-
-NOTE: These are only components for IP Masquerade functionality. You may need
-to also select additional options to match your specific network and hardware
-setup.
-
- * Now compile the kernel (make dep; make clean; make bzImage; make modules;
- make modules_install) , etc. Again, it is beyond the scope of this HOWTO
- if you have problems compiling your kernel. Please see Section 2.8 for
- URLs to the KERNEL howto, etc.
-
- * You will then have move over the kernel binary, update your bootloader
- (LILO, Grub, etc.), and reboot. If you have questions about kernel
- compiling, I highly recommend to consult some of the URLs above in this
- section.
-
-
------------------------------------------------------------------------------
-3.3. Assigning Private Network IP Addresses to the Internal LAN
-
-Since all INTERNAL MASQed machines should NOT have official Internet assigned
-addressees, there must be a specific and accepted way to allocate addresses
-to those machines without conflicting with anyone else's Internet address.
-
-From the original IP Masquerade FAQ:
-
-RFC 1918 is the official document on which IP addresses are to be used in a
-non-connected or "private" network. There are 3 blocks of numbers set aside
-specifically for this purpose.
-
-+-------------------------------------------------------------------------------+
-|Section 3: Private Address Space |
-| |
-|The Internet Assigned Numbers Authority (IANA) has reserved the |
-|following three blocks of the IP address space for private networks: |
-| |
-| 10.0.0.0 - 10.255.255.255 |
-| 172.16.0.0 - 172.31.255.255 |
-| 192.168.0.0 - 192.168.255.255 |
-| |
-|We will refer to the first block as "24-bit block", the second as "20-bit |
-|block", and the third as "16-bit" block". Note that the first block is |
-|nothing but a single class A network number, while the second block is a set |
-|of 16 continuous class B network numbers, and the third block is a set of 255 |
-|continuous class C network numbers. |
-+-------------------------------------------------------------------------------+
-
-For the record, my preference is to use the 192.168.0.0 network with a
-255.255.255.0 Class-C subnet mask and thus this HOWTO reflects this. Any of
-the above private networks are valid, but just be SURE to use the correct
-subnet-mask.
-
-So, if you're using a Class-C network, you should number your TCP/IP enabled
-machines as 192.168.0.1, 192.168.0.2, 192.168.0.3, .., 192.168.0.x
-
-192.168.0.1 is usually set as the internal gateway or Linux MASQ machine
-which reaches the external network. Please note that 192.168.0.0 and
-192.168.0.255 are the Network and Broadcast address respectively (these
-addresses are RESERVED). Avoid using these addresses on your machines or your
-network will not function properly.
------------------------------------------------------------------------------
-
-3.4. Configuring IP Forwarding Policies
-
-At this point, you should have your kernel and other required packages
-installed. All network IP addresses, gateway, and DNS addresses should be
-configured on your Linux MASQ server. If you don't know how to configure your
-Linux network cards, please consult the HOWTOs listed in either the 2.4.x
-Section 2.6, the 2.2.x Section 2.7, or the 2.0.x Section 2.8.
-
-Now, the only thing left to do is to configure the IP firewalling tools to
-both FORWARD and MASQUERADE the appropriate packets to the correct machine.
-
-** This section ONLY provides the user with the bare minimum firewall ruleset
-to get IP Masquerading working.
-
-Once IP MASQ has been successfully tested (as described later in this HOWTO),
-please refer to the Stronger IPTABLES ruleset for 2.4.x kernels in Section
-6.4.1, the Stronger IPCHAINS ruleset for 2.2.x kernels in Section 6.4.2, and
-the Stronger IPFWADM ruleset for 2.0.x kernels in Section 6.4.3. Please note
-that these stronger firewall rulesets are more of a template than
-anythingelse. For truly secure firewall rulesets, check out the the
-requirements section of the HOWTO ( 2.4.x - Section 2.6, 2.2.x - Section 2.7,
-2.0.x - Section 2.8.
-
-Instead of manually typing one of these files by hand, I recommend to simply
-browse the Example directory or [http://www.ecst.csuchico.edu/~dranch/LINUX/
-ipmasq/examples/rc.firewall-examples.tar.gz] download an archive of all of
-these rc.firewall files.
------------------------------------------------------------------------------
-
-3.4.1. Configuring IP Masquerade on Linux 2.4.x Kernels
-
-Please note that IPCHAINS is no longer the primary firewall configuration
-tool for the 2.4.x kernels. The new kernels now use the IPTABLES toolkit
-though the new 2.4.x kernels CAN still run most old IPCHAINS or IPFWADM
-rulesets via a compatiblity module. It should be noted that when in this
-mode, NO IPTABLES modules can be loaded. It should also be noted that none of
-the 2.2.x IPMASQ modules are compatible with 2.4.x kernels. For a more
-detailed reason for these changes, please see the Section 7.39 section.
-
-Ok, as mentioned before, the /etc/rc.d/rc.local script will load the script
-called /etc/rc.d/rc.firewall once after every reboot. The script will load
-all required IPMASQ modules as well as enable the IPMASQ function. In
-advanced setups, this same file would contain very secure firewall rulesets
-as well.
-
-Anyway, create the file /etc/rc.d/rc.firewall-2.4 with the following initial
-SIMPLE ruleset:
-
-
-+----------------------------------------------------------------------------------------+
-|#!/bin/sh |
-|# |
-|# rc.firewall-2.4 |
-|FWVER=0.75 |
-|# |
-|# Initial SIMPLE IP Masquerade test for 2.4.x kernels |
-|# using IPTABLES. |
-|# |
-|# Once IP Masquerading has been tested, with this simple |
-|# ruleset, it is highly recommended to use a stronger |
-|# IPTABLES ruleset either given later in this HOWTO or |
-|# from another reputable resource. |
-|# |
-|# |
-|# |
-|# Log: |
-|# 0.75 - Added more kernel modules to the comments section |
-|# 0.74 - the ruleset now uses modprobe vs. insmod |
-|# 0.73 - REJECT is not a legal policy yet; back to DROP |
-|# 0.72 - Changed the default block behavior to REJECT not DROP |
-|# 0.71 - Added clarification that PPPoE users need to use |
-|# "ppp0" instead of "eth0" for their external interface |
-|# 0.70 - Added commented option for IRC nat module |
-|# - Added additional use of environment variables |
-|# - Added additional formatting |
-|# 0.63 - Added support for the IRC IPTABLES module |
-|# 0.62 - Fixed a typo on the MASQ enable line that used eth0 |
-|# instead of $EXTIF |
-|# 0.61 - Changed the firewall to use variables for the internal |
-|# and external interfaces. |
-|# 0.60 - 0.50 had a mistake where the ruleset had a rule to DROP |
-|# all forwarded packets but it didn't have a rule to ACCEPT |
-|# any packets to be forwarded either |
-|# - Load the ip_nat_ftp and ip_conntrack_ftp modules by default |
-|# 0.50 - Initial draft |
-|# |
-| |
-|echo -e "\n\nLoading simple rc.firewall version $FWVER..\n" |
-| |
-| |
-|# The location of the iptables and kernel module programs |
-|# |
-|# If your Linux distribution came with a copy of iptables, |
-|# most likely all the programs will be located in /sbin. If |
-|# you manually compiled iptables, the default location will |
-|# be in /usr/local/sbin |
-|# |
-|# ** Please use the "whereis iptables" command to figure out |
-|# ** where your copy is and change the path below to reflect |
-|# ** your setup |
-|# |
-|#IPTABLES=/sbin/iptables |
-|IPTABLES=/usr/local/sbin/iptables |
-|DEPMOD=/sbin/depmod |
-|MODPROBE=/sbin/modprobe |
-| |
-| |
-|#Setting the EXTERNAL and INTERNAL interfaces for the network |
-|# |
-|# Each IP Masquerade network needs to have at least one |
-|# external and one internal network. The external network |
-|# is where the natting will occur and the internal network |
-|# should preferably be addressed with a RFC1918 private address |
-|# scheme. |
-|# |
-|# For this example, "eth0" is external and "eth1" is internal" |
-|# |
-|# |
-|# NOTE: If this doesnt EXACTLY fit your configuration, you must |
-|# change the EXTIF or INTIF variables above. For example: |
-|# |
-|# If you are a PPPoE or analog modem user: |
-|# |
-|# EXTIF="ppp0" |
-|# |
-|# |
-|EXTIF="eth0" |
-|INTIF="eth1" |
-|echo " External Interface: $EXTIF" |
-|echo " Internal Interface: $INTIF" |
-| |
-| |
-|#====================================================================== |
-|#== No editing beyond this line is required for initial MASQ testing == |
-| |
-| |
-|echo -en " loading modules: " |
-| |
-|# Need to verify that all modules have all required dependencies |
-|# |
-|echo " - Verifying that all kernel modules are ok" |
-|$DEPMOD -a |
-| |
-|# With the new IPTABLES code, the core MASQ functionality is now either |
-|# modular or compiled into the kernel. This HOWTO shows ALL IPTABLES |
-|# options as MODULES. If your kernel is compiled correctly, there is |
-|# NO need to load the kernel modules manually. |
-|# |
-|# NOTE: The following items are listed ONLY for informational reasons. |
-|# There is no reason to manual load these modules unless your |
-|# kernel is either mis-configured or you intentionally disabled |
-|# the kernel module autoloader. |
-|# |
-| |
-|# Upon the commands of starting up IP Masq on the server, the |
-|# following kernel modules will be automatically loaded: |
-|# |
-|# NOTE: Only load the IP MASQ modules you need. All current IP MASQ |
-|# modules are shown below but are commented out from loading. |
-|# =============================================================== |
-| |
-|echo "----------------------------------------------------------------------" |
-| |
-|#Load the main body of the IPTABLES module - "iptable" |
-|# - Loaded automatically when the "iptables" command is invoked |
-|# |
-|# - Loaded manually to clean up kernel auto-loading timing issues |
-|# |
-|echo -en "ip_tables, " |
-|$MODPROBE ip_tables |
-| |
-| |
-|#Load the IPTABLES filtering module - "iptable_filter" |
-|# - Loaded automatically when filter policies are activated |
-| |
-| |
-|#Load the stateful connection tracking framework - "ip_conntrack" |
-|# |
-|# The conntrack module in itself does nothing without other specific |
-|# conntrack modules being loaded afterwards such as the "ip_conntrack_ftp" |
-|# module |
-|# |
-|# - This module is loaded automatically when MASQ functionality is |
-|# enabled |
-|# |
-|# - Loaded manually to clean up kernel auto-loading timing issues |
-|# |
-|echo -en "ip_conntrack, " |
-|$MODPROBE ip_conntrack |
-| |
-| |
-|#Load the FTP tracking mechanism for full FTP tracking |
-|# |
-|# Enabled by default -- insert a "#" on the next line to deactivate |
-|# |
-|echo -en "ip_conntrack_ftp, " |
-|$MODPROBE ip_conntrack_ftp |
-| |
-| |
-|#Load the IRC tracking mechanism for full IRC tracking |
-|# |
-|# Enabled by default -- insert a "#" on the next line to deactivate |
-|# |
-|echo -en "ip_conntrack_irc, " |
-|$MODPROBE ip_conntrack_irc |
-| |
-| |
-|#Load the general IPTABLES NAT code - "iptable_nat" |
-|# - Loaded automatically when MASQ functionality is turned on |
-|# |
-|# - Loaded manually to clean up kernel auto-loading timing issues |
-|# |
-|echo -en "iptable_nat, " |
-|$MODPROBE iptable_nat |
-| |
-| |
-|#Loads the FTP NAT functionality into the core IPTABLES code |
-|# Required to support non-PASV FTP. |
-|# |
-|# Enabled by default -- insert a "#" on the next line to deactivate |
-|# |
-|echo -en "ip_nat_ftp, " |
-|$MODPROBE ip_nat_ftp |
-| |
-| |
-|#Loads the IRC NAT functionality into the core IPTABLES code |
-|# Required to support NAT of IRC DCC requests |
-|# |
-|# Disabled by default -- remove the "#" on the next line to activate |
-|# |
-|#echo -e "ip_nat_irc" |
-|#$MODPROBE ip_nat_irc |
-| |
-|echo "----------------------------------------------------------------------" |
-| |
-|# Just to be complete, here is a partial list of some of the other |
-|# IPTABLES kernel modules and their function. Please note that most |
-|# of these modules (the ipt ones) are automatically loaded by the |
-|# master kernel module for proper operation and don't need to be |
-|# manually loaded. |
-|# -------------------------------------------------------------------- |
-|# |
-|# ip_nat_snmp_basic - this module allows for proper NATing of some |
-|# SNMP traffic |
-|# |
-|# iptable_mangle - this target allows for packets to be |
-|# manipulated for things like the TCPMSS |
-|# option, etc. |
-|# |
-|# -- |
-|# |
-|# ipt_mark - this target marks a given packet for future action. |
-|# This automatically loads the ipt_MARK module |
-|# |
-|# ipt_tcpmss - this target allows to manipulate the TCP MSS |
-|# option for braindead remote firewalls. |
-|# This automatically loads the ipt_TCPMSS module |
-|# |
-|# ipt_limit - this target allows for packets to be limited to |
-|# to many hits per sec/min/hr |
-|# |
-|# ipt_multiport - this match allows for targets within a range |
-|# of port numbers vs. listing each port individually |
-|# |
-|# ipt_state - this match allows to catch packets with various |
-|# IP and TCP flags set/unset |
-|# |
-|# ipt_unclean - this match allows to catch packets that have invalid |
-|# IP/TCP flags set |
-|# |
-|# iptable_filter - this module allows for packets to be DROPped, |
-|# REJECTed, or LOGged. This module automatically |
-|# loads the following modules: |
-|# |
-|# ipt_LOG - this target allows for packets to be |
-|# logged |
-|# |
-|# ipt_REJECT - this target DROPs the packet and returns |
-|# a configurable ICMP packet back to the |
-|# sender. |
-|# |
-| |
-|echo -e " Done loading modules.\n" |
-| |
-| |
-| |
-|#CRITICAL: Enable IP forwarding since it is disabled by default since |
-|# |
-|# Redhat Users: you may try changing the options in |
-|# /etc/sysconfig/network from: |
-|# |
-|# FORWARD_IPV4=false |
-|# to |
-|# FORWARD_IPV4=true |
-|# |
-|echo " Enabling forwarding.." |
-|echo "1" > /proc/sys/net/ipv4/ip_forward |
-| |
-| |
-|# Dynamic IP users: |
-|# |
-|# If you get your IP address dynamically from SLIP, PPP, or DHCP, |
-|# enable this following option. This enables dynamic-address hacking |
-|# which makes the life with Diald and similar programs much easier. |
-|# |
-|echo " Enabling DynamicAddr.." |
-|echo "1" > /proc/sys/net/ipv4/ip_dynaddr |
-| |
-| |
-|# Enable simple IP forwarding and Masquerading |
-|# |
-|# NOTE: In IPTABLES speak, IP Masquerading is a form of SourceNAT or SNAT. |
-|# |
-|# NOTE #2: The following is an example for an internal LAN address in the |
-|# 192.168.0.x network with a 255.255.255.0 or a "24" bit subnet mask |
-|# connecting to the Internet on external interface "eth0". This |
-|# example will MASQ internal traffic out to the Internet but not |
-|# allow non-initiated traffic into your internal network. |
-|# |
-|# |
-|# ** Please change the above network numbers, subnet mask, and your |
-|# *** Internet connection interface name to match your setup |
-|# |
-| |
-| |
-|#Clearing any previous configuration |
-|# |
-|# Unless specified, the defaults for INPUT and OUTPUT is ACCEPT |
-|# The default for FORWARD is DROP (REJECT is not a valid policy) |
-|# |
-|echo " Clearing any existing rules and setting default policy.." |
-|$IPTABLES -P INPUT ACCEPT |
-|$IPTABLES -F INPUT |
-|$IPTABLES -P OUTPUT ACCEPT |
-|$IPTABLES -F OUTPUT |
-|$IPTABLES -P FORWARD DROP |
-|$IPTABLES -F FORWARD |
-|$IPTABLES -t nat -F |
-| |
-|echo " FWD: Allow all connections OUT and only existing and related ones IN" |
-|$IPTABLES -A FORWARD -i $EXTIF -o $INTIF -m state --state ESTABLISHED,RELATED -j ACCEPT |
-|$IPTABLES -A FORWARD -i $INTIF -o $EXTIF -j ACCEPT |
-|$IPTABLES -A FORWARD -j LOG |
-| |
-|echo " Enabling SNAT (MASQUERADE) functionality on $EXTIF" |
-|$IPTABLES -t nat -A POSTROUTING -o $EXTIF -j MASQUERADE |
-| |
-|echo -e "\nrc.firewall-2.4 v$FWVER done.\n" |
-+----------------------------------------------------------------------------------------+
-
-
-Once you are finished with editing the /etc/rc.d/rc.firewall ruleset, make it
-executable by typing in chmod 700 /etc/rc.d/rc.firewall-2.4
-
-Now that the firewall ruleset is ready, you need to let it run after every
-reboot. You could either do this by running it by hand everytime (such a
-pain) or add it to the boot scripts. We have covered two methods below:
-
-1. Redhat and Redhat-derived distros:
-
- * There are two ways to automatically load things in Redhat: /etc/rc.d/
- rc.local or a init script in /etc/rc.d/init.d/. The first method is the
- easiest. All you have to do is add the line:
-
- +---------------------------------------------------------------+
- |echo "Loading the rc.firewall ruleset.. " |
- |/etc/rc.d/rc.firewall-2.4 |
- +---------------------------------------------------------------+
-
- to the end of the /etc/rc.d/rc.local file and thats it (as described
- earlier in the HOWTO).
-
- The problem with this approach is that the firewall isn't executed until
- the last stages of booting. The preferred approach is to have the
- firewall loaded just after the networking subsystem is loaded. To do
- this, copy the following file into the /etc/rc.d/init.d directory:
-
-
- +-------------------------------------------------------------------------------+
- |#!/bin/sh |
- |# |
- |# chkconfig: 2345 11 89 |
- |# |
- |# description: Loads the rc.firewall-2.4 ruleset. |
- |# |
- |# processname: firewall-2.4 |
- |# pidfile: /var/run/firewall.pid |
- |# config: /etc/rc.d/rc.firewall-2.4 |
- |# probe: true |
- | |
- |# ---------------------------------------------------------------------------- |
- |# v05/24/03 |
- |# |
- |# Part of the copyrighted and trademarked TrinityOS document. |
- |# http://www.ecst.csuchico.edu/~dranch |
- |# |
- |# Written and Maintained by David A. Ranch |
- |# dranch@trinnet.net |
- |# |
- |# Updates |
- |# ------- |
- |# 05/24/03 - removed a old networking up check that had some |
- |# improper SGML ampersand conversions. |
- |# ---------------------------------------------------------------------------- |
- | |
- | |
- |# Source function library. |
- |. /etc/rc.d/init.d/functions |
- | |
- |# Check that networking is up. |
- | |
- |[ "XXXX${NETWORKING}" = "XXXXno" ] && exit 0 |
- | |
- |[ -x /sbin/ifconfig ] || exit 0 |
- | |
- |# The location of various iptables and other shell programs |
- |# |
- |# If your Linux distribution came with a copy of iptables, most |
- |# likely it is located in /sbin. If you manually compiled |
- |# iptables, the default location is in /usr/local/sbin |
- |# |
- |# ** Please use the "whereis iptables" command to figure out |
- |# ** where your copy is and change the path below to reflect |
- |# ** your setup |
- |# |
- |IPTABLES=/usr/local/sbin/iptables |
- | |
- | |
- |# See how we were called. |
- |case "$1" in |
- | start) |
- | /etc/rc.d/rc.firewall-2.4 |
- | ;; |
- | |
- | stop) |
- | echo -e "\nFlushing firewall and setting default policies to DROP\n" |
- | $IPTABLES -P INPUT DROP |
- | $IPTABLES -F INPUT |
- | $IPTABLES -P OUTPUT DROP |
- | $IPTABLES -F OUTPUT |
- | $IPTABLES -P FORWARD DROP |
- | $IPTABLES -F FORWARD |
- | $IPTABLES -F -t nat |
- | |
- | # Delete all User-specified chains |
- | $IPTABLES -X |
- | # |
- | # Reset all IPTABLES counters |
- | $IPTABLES -Z |
- | ;; |
- | |
- | restart) |
- | $0 stop |
- | $0 start |
- | ;; |
- | |
- | status) |
- | $IPTABLES -L |
- | ;; |
- | |
- | mlist) |
- | cat /proc/net/ip_conntrack |
- | ;; |
- | |
- | *) |
- | echo "Usage: firewall-2.4 {start|stop|status|mlist}" |
- | exit 1 |
- |esac |
- | |
- |exit 0 |
- +-------------------------------------------------------------------------------+
-
-
- With this script in place, run the command:
- +---------------------------------------------------------------+
- |chkconfig --level=345 firewall-2.4 on |
- +---------------------------------------------------------------+
- That's it! Now upon boot, the firewall will be loaded automatically.
-
-
-2. Slackware:
-
- * There are two ways to load things in Slackware: /etc/rc.d/rc.local or
- editing the /etc/rc.d/rc.inet2 file. The first method is the easiest. All
- you have to do is add the line:
-
- +---------------------------------------------------------------+
- |echo "Loading the rc.firewall ruleset.." |
- | |
- |/etc/rc.d/rc.firewall-2.4 |
- +---------------------------------------------------------------+
-
-
-Notes on how users might want to change the above firewall ruleset:
-
-You could also have IP Masquerading enabled on a PER MACHINE basis instead of
-the above method, which is enabling an ENTIRE TCP/IP network. For example,
-say if I wanted only the 192.168.0.2 and 192.168.0.8 hosts to have access to
-the Internet and NOT any of the other internal machines. I would change the
-in the "Enable simple IP forwarding and Masquerading" section (shown above)
-of the /etc/rc.d/rc.firewall ruleset.
-
-+---------------------------------------------------------------------------------+
-|#!/bin/sh |
-|# |
-|# Partial 2.4.x config to enable simple IP forwarding and Masquerading |
-|# v0.61 |
-|# |
-|# NOTE: The following is an example to allow only IP Masquerading for the |
-|# 192.168.0.2 and 192.168.0.8 machines with a 255.255.255.0 or a |
-|# "/24" subnet mask connecting to the Internet on interface eth0. |
-|# |
-|# ** Please change the network number, subnet mask, and the Internet |
-|# ** connection interface name to match your internal LAN setup |
-|# |
-|echo " - Setting the default FORWARD policy to DROP" |
-|$IPTABLES -P FORWARD DROP |
-| |
-|echo " - Enabling SNAT (IPMASQ) functionality on $EXTIF" |
-|$IPTABLES -t nat -A POSTROUTING -o $EXTIF -s 192.168.0.2/32 -j MASQUERADE |
-|$IPTABLES -t nat -A POSTROUTING -o $EXTIF -s 192.168.0.8/32 -j MASQUERADE |
-| |
-|echo " - Setting the FORWARD policy to 'DROP' all incoming / unrelated traffic" |
-|$IPTABLES -A INPUT -i $EXTIF -m state --state NEW,INVALID -j DROP |
-|$IPTABLES -A FORWARD -i $EXTIF -m state --state NEW,INVALID -j DROP |
-+---------------------------------------------------------------------------------+
-
-Common mistakes:
-
-It appears that a common mistake with new IP Masq users is to make the first
-command simply the following:
-
-+---------------------------------------------------------------------------+
-|IPTABLES: |
-|--------- |
-|iptables -t nat -A POSTROUTING -j MASQUERADE |
-+---------------------------------------------------------------------------+
-
-Do NOT make your default policy MASQUERADING. Otherwise, someone can
-manipulate their routing tables to tunnel straight back through your gateway,
-using it to masquerade their OWN identity!
-
-Again, you can add these lines to the /etc/rc.d/rc.firewall file, one of the
-other rc files you prefer, or do it manually every time you need IP
-Masquerade.
-
-Please see Section 6.4.1 for a detailed guide on a strong IPTABLES ruleset
-example. For additional details on IPTABLES usage, please refer to [http://
-www.netfilter.org/] http://www.netfilter.org/ for the primary IPTABLES site.
------------------------------------------------------------------------------
-
-3.4.2. Configuring IP Masquerade on Linux 2.2.x Kernels
-
-Please note that IPFWADM is no longer the firewall tool for manipulating IP
-Masquerading rules for both the 2.1.x and 2.2.x kernels. These new kernels
-now use the IPCHAINS toolkit. For a more detailed reason for this change,
-please see Chapter 7.
-
-Create the file /etc/rc.d/rc.firewall-2.2 with the following initial SIMPLE
-ruleset:
-
-
-+---------------------------------------------------------------------------------+
-|#!/bin/sh |
-|# |
-|# rc.firewall-2.2 |
-|# |
-|# - Initial SIMPLE IP Masquerade test for 2.1.x and 2.2.x kernels |
-|# using IPCHAINS. |
-|# |
-|# Once IP Masquerading has been tested, with this simple |
-|# ruleset, it is highly recommended to use a stronger |
-|# IPTABLES ruleset either given later in this HOWTO or |
-|# from another reputable resource. |
-| |
-|FWVER="1.22" |
-|# |
-|# 1.22 - ruleset now uses modprobe instead of insmod |
-|# 1.21 - Added clarification that PPPoE users need to use |
-|# "ppp0" instead of "eth0" for their external interface |
-|# 1.20 - Updated the script to use environment vars |
-|# 1.01 - Original version |
-| |
-| |
-|echo -e "\n\nLoading simple rc.firewall-2.2 : version $FWVER..\n" |
-| |
-| |
-|# The location of the ipchains and kernel module programs |
-|# |
-|# If your Linux distribution came with a copy of ipchains, |
-|# most likely all the programs will be located in /sbin. If |
-|# you manually compiled ipchains, the default location will |
-|# be in /usr/local/sbin |
-|# |
-|# ** Please use the "whereis ipchains" command to figure out |
-|# ** where your copy is and change the path below to reflect |
-|# ** your setup |
-|# |
-|IPCHAINS=/sbin/ipchains |
-|#IPTABLES=/usr/local/sbin/ipchains |
-|DEPMOD=/sbin/depmod |
-|MODPROBE=/sbin/modprobe |
-| |
-| |
-|#Setting the EXTERNAL and INTERNAL interfaces for the network |
-|# |
-|# Each IP Masquerade network needs to have at least one |
-|# external and one internal network. The external network |
-|# is where the NATing will occur and the internal network |
-|# should preferably be addressed with a RFC1918 private addressing |
-|# scheme. |
-|# |
-|# For this example, "eth0" is external and "eth1" is internal" |
-|# |
-|# NOTE: If this doesnt EXACTLY fit your configuration, you must |
-|# change the EXTIF or INTIF variables above. For example: |
-|# |
-|# If you are a PPPoE or analog modem user: |
-|# |
-|# EXTIF="ppp0" |
-|# |
-|# ** Please change this to reflect your specific configuration ** |
-|# |
-|EXTIF="eth0" |
-|INTIF="eth1" |
-|echo " External Interface: $EXTIF" |
-|echo " Internal Interface: $INTIF" |
-| |
-| |
-|# Network Address of the Internal Network |
-|# |
-|# This example rc.firewall file uses the 192.168.0.0 network |
-|# with a /24 or 255.255.255.0 netmask. |
-|# |
-|# ** Change this variable to reflect your specific setup ** |
-|# |
-|INTLAN="192.168.0.0/24" |
-|echo -e " Internal Interface: $INTLAN\n" |
-| |
-| |
-| |
-|# Load all required IP MASQ modules |
-|# |
-|# NOTE: Only load the IP MASQ modules you need. All current IP MASQ modules |
-|# are shown below but are commented out from loading. |
-|echo " loading required IPMASQ kernel modules.." |
-| |
-|# Needed to initially load modules |
-|# |
-|$DEPMOD -a |
-| |
-|echo -en " Loading modules: " |
-| |
-|# Supports the proper masquerading of FTP file transfers using the PORT method |
-|# |
-|echo -en "FTP, " |
-|$MODPROBE ip_masq_ftp |
-| |
-|# Supports the masquerading of RealAudio over UDP. Without this module, |
-|# RealAudio WILL function but in TCP mode. This can cause a reduction |
-|# in sound quality |
-|# |
-|#echo -en "RealAudio, " |
-|$MODPROBE ip_masq_raudio |
-| |
-|# Supports the masquerading of IRC DCC file transfers |
-|# |
-|#echo -en "Irc, " |
-|#$MODPROBE ip_masq_irc |
-| |
-| |
-|# Supports the masquerading of Quake and QuakeWorld by default. This modules is |
-|# for for multiple users behind the Linux MASQ server. If you are going to |
-|# play Quake I, II, and III, use the second example. |
-|# |
-|# NOTE: If you get ERRORs loading the QUAKE module, you are running an old |
-|# ----- kernel that has bugs in it. Please upgrade to the newest kernel. |
-|# |
-|#echo -en "Quake, " |
-|#Quake I / QuakeWorld (ports 26000 and 27000) |
-|#$MODPROBE ip_masq_quake |
-|# |
-|#Quake I/II/III / QuakeWorld (ports 26000, 27000, 27910, 27960) |
-|#$MODPROBE ip_masq_quake 26000,27000,27910,27960 |
-| |
-| |
-|# Supports the masquerading of the CuSeeme video conferencing software |
-|# |
-|#echo -en "CuSeeme, " |
-|#$MODPROBE ip_masq_cuseeme |
-| |
-|#Supports the masquerading of the VDO-live video conferencing software |
-|# |
-|#echo -en "VdoLive " |
-|#$MODPROBE ip_masq_vdolive |
-| |
-|echo ". Done loading modules." |
-| |
-| |
-|#CRITICAL: Enable IP forwarding since it is disabled by default since |
-|# |
-|# Redhat Users: you may try changing the options in |
-|# /etc/sysconfig/network from: |
-|# |
-|# FORWARD_IPV4=false |
-|# to |
-|# FORWARD_IPV4=true |
-|# |
-|echo " enabling forwarding.." |
-|echo "1" > /proc/sys/net/ipv4/ip_forward |
-| |
-| |
-|#CRITICAL: Enable automatic IP defragmenting since it is disabled by default |
-|# in 2.2.x kernels. This used to be a compile-time option but the |
-|# behavior was changed in 2.2.12 |
-|# |
-|echo " enabling AlwaysDefrag.." |
-|echo "1" > /proc/sys/net/ipv4/ip_always_defrag |
-| |
-| |
-|# Dynamic IP users: |
-|# |
-|# If you get your IP address dynamically from SLIP, PPP, or DHCP, enable this |
-|# following option. This enables dynamic-ip address hacking in IP MASQ, |
-|# making the life with Diald and similar programs much easier. |
-|# |
-|#echo " enabling DynamicAddr.." |
-|#echo "1" > /proc/sys/net/ipv4/ip_dynaddr |
-| |
-| |
-|# Enable the LooseUDP patch which some Internet-based games require |
-|# |
-|# If you are trying to get an Internet game to work through your IP MASQ box, |
-|# and you have set it up to the best of your ability without it working, try |
-|# enabling this option (delete the "#" character). This option is disabled |
-|# by default due to possible internal machine UDP port scanning |
-|# vulnerabilities. |
-|# |
-|#echo " enabling LooseUDP.." |
-|#echo "1" > /proc/sys/net/ipv4/ip_masq_udp_dloose |
-| |
-| |
-|#Clearing any previous configuration |
-|# |
-|# Unless specified, the defaults for INPUT and OUTPUT is ACCEPT |
-|# The default for FORWARD is REJECT |
-|# |
-|echo " clearing any existing rules and setting default policy.." |
-|$IPCHAINS -P input ACCEPT |
-|$IPCHAINS -P output ACCEPT |
-|$IPCHAINS -P forward REJECT |
-|$IPCHAINS -F input |
-|$IPCHAINS -F output |
-|$IPCHAINS -F forward |
-| |
-| |
-|# MASQ timeouts |
-|# |
-|# 2 hrs timeout for TCP session timeouts |
-|# 10 sec timeout for traffic after the TCP/IP "FIN" packet is received |
-|# 160 sec timeout for UDP traffic (Important for MASQ'ed ICQ users) |
-|# |
-|echo " setting default timers.." |
-|$IPCHAINS -M -S 7200 10 160 |
-| |
-| |
-|# DHCP: For people who receive their external IP address from either DHCP or |
-|# BOOTP such as ADSL or Cablemodem users, it is necessary to use the |
-|# following before the deny command. |
-|# |
-|# This example is currently commented out. |
-|# |
-|# |
-|#$IPCHAINS -A input -j ACCEPT -i $EXTIF -s 0/0 67 -d 0/0 68 -p udp |
-| |
-|# Enable simple IP forwarding and Masquerading |
-|# |
-|# NOTE: The following is an example for an internal LAN address in the |
-|# 192.168.0.x network with a 255.255.255.0 or a "24" bit subnet mask |
-|# connecting to the Internet on interface eth0. |
-|# |
-|# ** Please change this network number, subnet mask, and your Internet |
-|# ** connection interface name to match your internal LAN setup |
-|# |
-|echo " enabling IPMASQ functionality on $EXTIF" |
-|$IPCHAINS -P forward DENY |
-|$IPCHAINS -A forward -i $EXTIF -s $INTLAN -j MASQ |
-| |
-|echo -e "\nrc.firewall-2.2 v$FWVER done.\n" |
-+---------------------------------------------------------------------------------+
-
-
-Once you are finished with editing the /etc/rc.d/rc.firewall ruleset, make it
-executable by typing in chmod 700 /etc/rc.d/rc.firewall
-
-Now that the firewall ruleset is ready, you need to let it run after every
-reboot. You could either do this by running it by hand everytime (such a
-pain) or add it to the boot scripts. We have covered two methods below:
-
-1. Redhat and Redhat-derived distros:
-
- * There are two ways to automatically load things in Redhat: /etc/rc.d/
- rc.local or a init script in /etc/rc.d/init.d/. The first method is the
- easiest. All you have to do is add the line:
-
- +---------------------------------------------------------------+
- |echo "Loading the rc.firewall ruleset.." |
- |/etc/rc.d/rc.firewall-2.2 |
- +---------------------------------------------------------------+
-
- to the end of the /etc/rc.d/rc.local file and thats it (as described
- earlier in the HOWTO).
-
- The problem with this approach is that the firewall isn't executed until
- the last stages of booting. The preferred approach is to have the
- firewall loaded just after the networking subsystem is loaded. To do
- this, copy the following file into the /etc/rc.d/init.d directory:
-
-
- +-------------------------------------------------------------------------------+
- |#!/bin/sh |
- |# |
- |# chkconfig: 2345 11 89 |
- |# |
- |# description: Loads the rc.firewall-2.2 ruleset. |
- |# |
- |# processname: firewall-2.2 |
- |# pidfile: /var/run/firewall.pid |
- |# config: /etc/rc.d/rc.firewall-2.2 |
- |# probe: true |
- | |
- |# ---------------------------------------------------------------------------- |
- |# v08/29/02 |
- |# |
- |# Part of the copyrighted and trademarked TrinityOS document. |
- |# http://www.ecst.csuchico.edu/~dranch |
- |# |
- |# Written and Maintained by David A. Ranch |
- |# dranch@trinnet.net |
- |# |
- |# Updates |
- |# ------- |
- |# |
- |# ---------------------------------------------------------------------------- |
- | |
- | |
- |# Source function library. |
- |. /etc/rc.d/init.d/functions |
- | |
- |# Check that networking is up. |
- | |
- |# This line no longer work with bash2 |
- |#[ ${NETWORKING} = "no" ] && exit 0 |
- |# This should be OK. |
- |[ "XXXX${NETWORKING}" = "XXXXno" ] && exit 0 |
- | |
- |[ -x /sbin/ifconfig ] || exit 0 |
- | |
- |# The location of various iptables and other shell programs |
- |# |
- |# If your Linux distribution came with a copy of iptables, most |
- |# likely it is located in /sbin. If you manually compiled |
- |# iptables, the default location is in /usr/local/sbin |
- |# |
- |# ** Please use the "whereis iptables" command to figure out |
- |# ** where your copy is and change the path below to reflect |
- |# ** your setup |
- |# |
- |IPCHAINS=/sbin/ipchains |
- | |
- | |
- |# See how we were called. |
- |case "$1" in |
- | start) |
- | /etc/rc.d/rc.firewall-2.2 |
- | ;; |
- | |
- | stop) |
- | echo -e "\nFlushing firewall and setting default policies to REJECT\n" |
- | |
- | $IPCHAINS -P input REJECT |
- | $IPCHAINS -P output REJECT |
- | $IPCHAINS -P forward REJECT |
- | |
- | $IPCHAINS -F input |
- | $IPCHAINS -F output |
- | $IPCHAINS -F forward |
- | ;; |
- | |
- | restart) |
- | $0 stop |
- | $0 start |
- | ;; |
- | |
- | status) |
- | $IPCHAINS -L |
- | ;; |
- | |
- | mlist) |
- | $IPCHAINS -M -L |
- | ;; |
- | |
- | *) |
- | echo "Usage: firewall-2.2 {start|stop|status|mlist}" |
- | exit 1 |
- |esac |
- | |
- |exit 0 |
- +-------------------------------------------------------------------------------+
-
-
- With this script in place, run the command:
- +---------------------------------------------------------------+
- |chkconfig --level=345 firewall-2.2 on |
- +---------------------------------------------------------------+
- That's it! Now upon boot, the firewall will be loaded automatically.
-
-
-2. Slackware:
-
- * There are two ways to load things in Slackware: /etc/rc.d/rc.local or
- editing the /etc/rc.d/rc.inet2 file. The first method is the easiest. All
- you have to do is add the line:
-
- +---------------------------------------------------------------+
- |echo "Loading the rc.firewall ruleset.." |
- | |
- |/etc/rc.d/rc.firewall-2.2 |
- +---------------------------------------------------------------+
-
- to the end of the /etc/rc.d/rc.local file and thats it. The problem with
- this approach is that if you are running a STRONG firewall ruleset, the
- firewall isn't executed until the last stages of booting. The preferred
- approach is to have the firewall loaded just after the networking
- subsystem is loaded. For now, the HOWTO only covers how to do so using /
- etc/rc.d/rc.local. If you want a stronger system, I recommend you check
- out Section 10 of TrinityOS found in the links section at the bottom of
- this HOWTO.
-
-
-Notes on how users might want to change the above firewall ruleset:
-
-You could also have IP Masquerading enabled on a PER MACHINE basis instead of
-the above method, which is enabling an ENTIRE TCP/IP network. For example,
-say if I wanted only the 192.168.0.2 and 192.168.0.8 hosts to have access to
-the Internet and NOT any of the other internal machines. I would change the
-in the "Enable simple IP forwarding and Masquerading" section (shown above)
-of the /etc/rc.d/rc.firewall ruleset.
-
-+-------------------------------------------------------------------------------+
-|#!/bin/sh |
-|# |
-|# Enable simple IP forwarding and Masquerading |
-|# v1.01 |
-|# |
-|# NOTE: The following is an example used in addition to the simple |
-|# IPCHAINS ruleset anove to allow only IP Masquerading for the |
-|# 192.168.0.2 and 192.168.0.8 machines with a 255.255.255.0 or a |
-|# "24" bit subnet mask connecting to the Internet on interface $EXTIF. |
-|# |
-|# ** Please change the network number, subnet mask, and the Internet |
-|# ** connection interface name to match your internal LAN setup |
-|# |
-|$IPCHAINS -P forward DENY |
-|$IPCHAINS -A forward -i $EXTIF -s 192.168.0.2/32 -j MASQ |
-|$IPCHAINS -A forward -i $EXTIF -s 192.168.0.8/32 -j MASQ |
-+-------------------------------------------------------------------------------+
-
-Common mistakes:
-
-What appears to be a common mistake with new IP MASQ users is to make the
-first command:
-
-+---------------------------------------------------------------------------+
-|$IPCHAINS -P forward masquerade |
-+---------------------------------------------------------------------------+
-
-Do NOT make your default policy MASQUERADING. Otherwise, someone can
-manipulate their routing tables to tunnel straight back through your gateway,
-using it to masquerade their OWN identity!
-
-Again, you can add these lines to the /etc/rc.d/rc.firewall file, one of the
-other rc files you prefer, or do it manually every time you need IP
-Masquerade.
-
-Please see Section 6.4.2 for a detailed guide on IPCHAINS and a strong
-IPCHAINS ruleset example. For additional details on IPCHAINS usage, please
-refer to [http://www.netfilter.org/ipchains/] http://www.netfilter.org/
-ipchains/ for the primary IPCHAINS site or the [http://www.tldp.org/HOWTO/
-IPCHAINS-HOWTO.html] Linux IP CHAINS HOWTO Backup site
------------------------------------------------------------------------------
-
-3.4.3. Configuring IP Masquerade on Linux 2.0.x Kernels
-
-Create the file /etc/rc.d/rc.firewall with the following initial SIMPLE
-ruleset:
-+---------------------------------------------------------------------------------+
-|#!/bin/sh |
-|# |
-|# rc.firewall-2.0 |
-|# |
-|# A Initial SIMPLE IP Masquerade setup for 2.0.x kernels using IPFWADM |
-|# |
-|FWVER="2.02" |
-|# |
-|# 2.02 - Added clarification that PPPoE users need to use |
-|# "ppp0" instead of "eth0" for their external interface |
-|# |
-|# |
-|# Once IP Masquerading has been tested, with this simple |
-|# ruleset, it is highly recommended to use a stronger |
-|# IPTABLES ruleset either given later in this HOWTO or |
-|# from another reputable resource. |
-|# |
-|echo -e "\n\nLoading simple rc.firewall version $FWVER..\n" |
-| |
-| |
-|#Setting the EXTERNAL and INTERNAL interfaces for the network |
-|# |
-|# Each IP Masquerade network needs to have at least one |
-|# external and one internal network. The external network |
-|# is where the NATing will occur and the internal network |
-|# should preferably be addressed with a RFC1918 private addressing |
-|# scheme. |
-|# |
-|# For this example, "eth0" is external and "eth1" is internal" |
-|# |
-|# NOTE: If this doesnt EXACTLY fit your configuration, you must |
-|# change the EXTIF or INTIF variables above. For example: |
-|# |
-|# If you are a PPPoE or analog modem user: |
-|# |
-|# EXTIF="ppp0" |
-|# |
-|# ** Please change this to reflect your specific configuration ** |
-|# |
-|EXTIF="eth0" |
-|INTIF="eth1" |
-|echo " External Interface: $EXTIF" |
-|echo " Internal Interface: $INTIF" |
-| |
-| |
-|# Network Address of the Internal Network |
-|# |
-|# This example rc.firewall file uses the 192.168.0.0 network |
-|# with a /24 or 255.255.255.0 netmask. |
-|# |
-|# ** Change this variable to reflect your specific setup ** |
-|# |
-|INTLAN="192.168.0.0/24" |
-|echo -e " Internal Interface: $INTLAN\n" |
-| |
-| |
-|# Load all required IP MASQ modules |
-|# |
-|# NOTE: Only load the IP MASQ modules you need. All current available IP |
-|# MASQ modules are shown below but are commented out from loading. |
-|echo -en "Loading modules: " |
-| |
-| |
-|# Needed to initially load modules |
-|# |
-|/sbin/depmod -a |
-| |
-|# Supports the proper masquerading of FTP file transfers using the PORT method |
-|# |
-|echo -en "FTP, " |
-|/sbin/modprobe ip_masq_ftp |
-| |
-|# Supports the masquerading of RealAudio over UDP. Without this module, |
-|# RealAudio WILL function but in TCP mode. This can cause a reduction |
-|# in sound quality |
-|# |
-|#echo -en "RealAudio, " |
-|#/sbin/modprobe ip_masq_raudio |
-| |
-|# Supports the masquerading of IRC DCC file transfers |
-|# |
-|#echo -en "Irc, " |
-|#/sbin/modprobe ip_masq_irc |
-| |
-|# Supports the masquerading of Quake and QuakeWorld by default. These modules |
-|# are for multiple users behind the Linux MASQ server. If you are going to |
-|# play Quake I, II, and III, use the second example. |
-|# |
-|# NOTE: If you get ERRORs loading the QUAKE module, you are running an old |
-|# ----- kernel that has bugs in it. Please upgrade to the newest kernel. |
-|# |
-|#echo -en "Quake, " |
-|#Quake I / QuakeWorld (ports 26000 and 27000) |
-|#/sbin/modprobe ip_masq_quake |
-|# |
-|#Quake I/II/III / QuakeWorld (ports 26000, 27000, 27910, 27960) |
-|#/sbin/modprobe ip_masq_quake 26000,27000,27910,27960 |
-| |
-|# Supports the masquerading of the CuSeeme video conferencing software |
-|# |
-|#echo -en "CuSeeme, " |
-|#/sbin/modprobe ip_masq_cuseeme |
-| |
-|#Supports the masquerading of the VDO-live video conferencing software |
-|# |
-|#echo -en "VdoLive, " |
-|#/sbin/modprobe ip_masq_vdolive |
-| |
-|echo ". Done loading modules." |
-| |
-| |
-|#CRITICAL: Enable IP forwarding since it is disabled by default |
-|# |
-|# Redhat Users: you may try changing the options in |
-|# /etc/sysconfig/network from: |
-|# |
-|# FORWARD_IPV4=false |
-|# to |
-|# FORWARD_IPV4=true |
-|# |
-|echo " enabling forwarding.." |
-|echo "1" > /proc/sys/net/ipv4/ip_forward |
-| |
-| |
-|#CRITICAL: Enable automatic IP defragmenting since it is disabled by default |
-|# |
-|# This used to be a compile-time option but the behavior was changed |
-|# in 2.2.12. This option is required for both 2.0 and 2.2 kernels. |
-|# |
-|echo " enabling AlwaysDefrag.." |
-|echo "1" > /proc/sys/net/ipv4/ip_always_defrag |
-| |
-| |
-|# Dynamic IP users: |
-|# |
-|# If you get your Internet IP address dynamically from SLIP, PPP, or DHCP, |
-|# enable the following option. This enables dynamic-ip address hacking in |
-|# IP MASQ, making the life with DialD, PPPd, and similar programs much easier. |
-|# |
-|#echo " enabling DynamicAddr.." |
-|#echo "1" > /proc/sys/net/ipv4/ip_dynaddr |
-| |
-| |
-|#Clearing any previous configuration |
-|# |
-|# Unless specified, the defaults for INPUT and OUTPUT is ACCEPT |
-|# The default for FORWARD is REJECT |
-|# |
-|echo " clearing any existing rules and setting default policy.." |
-|/sbin/ipfwadm -I -p accept |
-|/sbin/ipfwadm -O -p accept |
-|/sbin/ipfwadm -F -p reject |
-|/sbin/ipfwadm -I -f |
-|/sbin/ipfwadm -O -f |
-|/sbin/ipfwadm -F -f |
-| |
-| |
-|# MASQ timeouts |
-|# |
-|# 2 hrs timeout for TCP session timeouts |
-|# 10 sec timeout for traffic after the TCP/IP "FIN" packet is received |
-|# 160 sec timeout for UDP traffic (Important for MASQ'ed ICQ users) |
-|# |
-|echo " setting default timers.." |
-|/sbin/ipfwadm -M -s 7200 10 160 |
-| |
-| |
-|# DHCP: For people who receive their external IP address from either DHCP or |
-|# BOOTP such as ADSL or Cablemodem users, it is necessary to use the |
-|# following before the deny command. |
-|# |
-|# This example is currently commented out. |
-|# |
-|# |
-|#/sbin/ipfwadm -I -a accept -S 0/0 67 -D 0/0 68 -W $EXTIF -P udp |
-| |
-| |
-|# Enable simple IP forwarding and Masquerading |
-|# |
-|# NOTE: The following is an example for an internal LAN address in the |
-|# 192.168.0.x network with a 255.255.255.0 or a "24" bit subnet mask |
-|# connecting to the Internet on interface eth0. |
-|# |
-|# ** Please change this network number, subnet mask, and your Internet |
-|# ** connection interface name to match your internal LAN setup. |
-|# |
-|echo " enabling IPMASQ functionality on $EXTIF" |
-|/sbin/ipfwadm -F -p deny |
-|/sbin/ipfwadm -F -a m -W $EXTIF -S $INTLAN -D 0.0.0.0/0 |
-| |
-|echo -e "\nrc.firewall-2.0 v$FWVER done.\n" |
-+---------------------------------------------------------------------------------+
-
-
-Once you are finished with editing the /etc/rc.d/rc.firewall ruleset, make it
-executable by typing in "chmod 700 /etc/rc.d/rc.firewall"
-
-Now that the firewall ruleset is ready to go, you need to let it run after
-every reboot. You could either do this by running it by hand everytime (such
-a pain) or add it to the boot scripts. We have covered two methods below:
-
-Redhat and Redhat-derived distros:
-
- * There are two ways to automatically load things in Redhat: /etc/rc.d/
- rc.local or a init script in /etc/rc.d/init.d/. The first method is the
- easiest. All you have to do is add the line:
-
- +---------------------------------------------------------------+
- |echo "Loading the rc.firewall ruleset.." |
- | |
- |/etc/rc.d/rc.firewall |
- +---------------------------------------------------------------+
-
- The problem with this approach is that the firewall isn't executed until
- the last stages of booting. The preferred approach is to have the
- firewall loaded just after the networking subsystem is loaded. To do
- this, copy the following file into the /etc/rc.d/init.d directory:
-
-
- +-------------------------------------------------------------------------------+
- |#!/bin/sh |
- |# |
- |# chkconfig: 2345 11 89 |
- |# |
- |# description: Loads the rc.firewall-2.0 ruleset. |
- |# |
- |# processname: firewall-2.0 |
- |# pidfile: /var/run/firewall.pid |
- |# config: /etc/rc.d/rc.firewall-2.0 |
- |# probe: true |
- | |
- |# ---------------------------------------------------------------------------- |
- |# v02/09/02 |
- |# |
- |# Part of the copyrighted and trademarked TrinityOS document. |
- |# http://www.ecst.csuchico.edu/~dranch |
- |# |
- |# Written and Maintained by David A. Ranch |
- |# dranch@trinnet.net |
- |# |
- |# Updates |
- |# ------- |
- |# |
- |# ---------------------------------------------------------------------------- |
- | |
- | |
- |# Source function library. |
- |. /etc/rc.d/init.d/functions |
- | |
- |# Check that networking is up. |
- | |
- |# This line no longer work with bash2 |
- |#[ ${NETWORKING} = "no" ] && exit 0 |
- |# This should be OK. |
- |[ "XXXX${NETWORKING}" = "XXXXno" ] && exit 0 |
- | |
- |[ -x /sbin/ifconfig ] || exit 0 |
- | |
- |# The location of various iptables and other shell programs |
- |# |
- |# If your Linux distribution came with a copy of iptables, most |
- |# likely it is located in /sbin. If you manually compiled |
- |# iptables, the default location is in /usr/local/sbin |
- |# |
- |# ** Please use the "whereis iptables" command to figure out |
- |# ** where your copy is and change the path below to reflect |
- |# ** your setup |
- |# |
- |IPFWADM=/sbin/ipfwadm |
- | |
- | |
- |# See how we were called. |
- |case "$1" in |
- | start) |
- | /etc/rc.d/rc.firewall-2.0 |
- | ;; |
- | |
- | stop) |
- | echo -e "\nFlushing firewall and setting default policies to REJECT\n" |
- | |
- | $IPFWADM -I -p REJECT |
- | $IPFWADM -O -p REJECT |
- | $IPFWADM -F -p REJECT |
- | |
- | $IPFWADM -I -f |
- | $IPFWADM -O -f |
- | $IPFWADM -F -f |
- | ;; |
- | |
- | restart) |
- | $0 stop |
- | $0 start |
- | ;; |
- | |
- | status) |
- | $IPFWADM -l |
- | ;; |
- | |
- | mlist) |
- | $IPFWADM -M -l |
- | ;; |
- | |
- | *) |
- | echo "Usage: firewall-2.0 {start|stop|status|mlist}" |
- | exit 1 |
- |esac |
- | |
- |exit 0 |
- +-------------------------------------------------------------------------------+
-
-
- With this script in place, run the command:
- +---------------------------------------------------------------+
- |chkconfig --level=345 firewall-2.0 on |
- +---------------------------------------------------------------+
- That's it! Now upon boot, the firewall will be loaded automatically.
-
-
-Slackware:
-
- * There are two ways to automatically load things in Slackware: /etc/rc.d/
- rc.local or editing the /etc/rc.d/rc.inet2 file. The first method is the
- easiest. All you have to do is add the line:
-
- +---------------------------------------------------------------+
- |echo "Loading the rc.firewall ruleset.." |
- | |
- |/etc/rc.d/rc.firewall-2.0 |
- +---------------------------------------------------------------+
-
- to the end of the /etc/rc.d/rc.local file and thats it. The problem with
- this approach is that if you are running a STRONG firewall ruleset, the
- firewall isn' t executed until the last stages of booting. The preferred
- approach is to have the firewall loaded just after the networking
- subsystem is loaded. For now, the HOWTO only covers how to do so using /
- etc/rc.d/rc.local. If you want the strong er system, I recommend you
- check out Section 10 of TrinityOS found in the links section at the
- bottom of this HOWTO.
-
-
-Notes on how users might want to change the above firewall ruleset:
-
-You could have also enabled IP Masquerading on a PER MACHINE basis instead of
-the above method enabling an ENTIRE TCP/IP network. For example, say if I
-wanted only the 192.168.0.2 and 192.168.0.8 hosts to have access to the
-Internet and NOT any of the other internal machines. I would change the in
-the "Enable simple IP forwarding and Masquerading" section (shown above) of
-the /etc/rc.d/rc.firewall ruleset.
-
-+---------------------------------------------------------------------------------+
-|# Enable simple IP forwarding and Masquerading |
-|# v2.01 |
-|# |
-|# NOTE: The following is an example to only allow IP Masquerading for the |
-|# 192.168.0.2 and 192.168.0.8 machines with a 255.255.255.0 or a "24" |
-|# bit subnet mask connected to the Internet on interface eth0. |
-|# |
-|# ** Please change this network number, subnet mask, and your Internet |
-|# ** connection interface name to match your internal LAN setup |
-|# |
-|# Please use the following in ADDITION to the simple rulesets above for |
-|# specific MASQ networks. |
-|# |
-|/sbin/ipfwadm -F -p deny |
-|/sbin/ipfwadm -F -a m -W $EXTIF -S 192.168.0.2/32 -D 0.0.0.0/0 |
-|/sbin/ipfwadm -F -a m -W $EXTIF -S 192.168.0.8/32 -D 0.0.0.0/0 |
-+---------------------------------------------------------------------------------+
-
-Common mistakes:
-
-What appears to be a common mistake with new IP Masq users is to make the
-first command:
-
-+---------------------------------------------------------------------------+
-|ipfwadm -F -p masquerade |
-+---------------------------------------------------------------------------+
-
-Do NOT make your default policy MASQUERADING. Otherwise, someone who has the
-ability to manipulate their routing tables will be able to tunnel straight
-back through your gateway, using it to masquerade their OWN identity!
-
-Again, you can add these lines to the /etc/rc.d/rc.firewall file, one of the
-other rc files (if you prefer), or manually add those lines every time you
-need IP Masquerade.
-
-Please see Section 6.4.2 and Section 6.4.3for a detailed guide and stronger
-examples of IPCHAINS and IPFWADM ruleset examples.
------------------------------------------------------------------------------
-
-Chapter 4. Configuring the other internal to-be MASQed machines
-
-Besides setting the appropriate IP address for each internal MASQed machine
-(either statically or though DHCP), you should also set each internal machine
-with the appropriate gateway IP address of the Linux MASQ server and required
-DNS servers. In general, this is rather straight forward. You simply enter
-the address of your Linux host (192.168.0.1 is used throughout this HOWTO) as
-the machine's gateway address.
-
-For the Domain Name Service (DNS), you add in any DNS servers that are
-available to you to use. The most apparent one(s) should be the DNS servers
-that your Linux server uses. You can optionally add any "domain search"
-suffix as well for quicker connections, etc.
-
-After you have properly reconfigured the internal MASQed machines, remember
-to restart their appropriate network services or reboot them if need be.
-
-The following configuration instructions assume that you are using a Class C
-network with 192.168.0.1 as your Linux MASQ server's address. Please note
-that 192.168.0.0 and 192.168.0.255 are reserved TCP/IP address per RFC1918
-for uses just like enabling IP Masquerade services.
-
-As it stands, the following Platforms have been tested as internal MASQed
-machines. This is only an EXAMPLE of all compatible OSes out there:
-
- * Apple Macintosh OS and OS-X (with MacTCP or Open Transport or the BSD TCP
- /IP stack)
-
- * AT&T Unix (Caldera)
-
- * *BSD systems including Free/Net/Open/BSDi/386/etc.
-
- * Commodore Amiga (with AmiTCP or AS225-stack)
-
- * Digital VAX Stations 3520 and 3100 with UCX (TCP/IP stack for VMS)
-
- * Digital Ultrix, Digital Unix (Compaq Tru/64)
-
- * HP HP/UX
-
- * IBM AIX running on RS/6000, PowerPC, etc.
-
- * IBM OS/2 (including Warp v3)
-
- * IBM OS400 running on a AS/400
-
- * Linux distributions from vendors like Caldera, Corel, Debian, Mandrake,
- Redhat, Slackware, SuSe, etc. running various kernels like 1.2.x, 1.3.x,
- 2.0.x, 2.1.x, 2.2.x, 2.3.x, 2.4.x, etc.
-
- * Microsoft DOS (with NCSA Telnet package, DOS Trumpet works partially)
-
- * Microsoft Windows 3.1 (with the Netmanage or FTP packages)
-
- * Microsoft Windows For Workgroup 3.11 (with a TCP/IP package)
-
- * Microsoft Windows 95, OSR2, 98, 98se, Me
-
- * Microsoft Windows NT 3.51, 4.0, 2000, XP - (both workstation
- (professional) and server versions)
-
- * Novell Netware 4.01, 5.x, etc. with the TCP/IP service
-
- * SCO Openserver (v3.2.4.2 and 5) and UnixWare (AT&T Unix)
-
- * Sun Solaris 2.51, 2.6, 7, 8
-
- * heheh.. what else am I missing?
-
-
------------------------------------------------------------------------------
-4.1. Configuring Microsoft Windows 95 and OSR2
-
- 1. ** Please note that some prompts might be different based upon the build
- version of Windows95 you are running **
-
- If you haven't installed your network card and adapter driver, do so now.
- Descriptions to perform this step is beyond the scope of this document
- and though it is fairly simple, if you haven't done this before, please
- seek assitance.
-
- 2. Go to the 'Control Panel' --> 'Network'.
-
- 3. Click on Add --> Protocol --> Manufacture: Microsoft --> Protocol: 'TCP/
- IP protocol' if you don't already have it installed.
-
- 4. Highlight the TCP/IP item bound to your correct Windows95 network card
- e.g. (TCP/IP --> Intel EtherExpress Pro/100+) and select 'Properties'.
- Here, you have two options: configure a static address or use DHCP.
- Static addresses are simple but require that you NEVER configure
- duplication IPs on different machines. The alternative is DHCP which
- automatically configures all DHCP-enabled workstations things like IP
- addresses, DNS servers, etc. from a central server (typically the Linux
- MASQ server).
-
- DHCP enabled:
-
- To use DHCP, simply click on the "Use DHCP to assign addresses" button.
- Please note that configuring a DHCP server is beyond the scope of this
- HOWTO but it is fully covered in TrinityOS and other Linux HOWTOs.
-
- Static Addresses:
-
- Now goto the 'IP Address' tab and set IP Address to 192.168.0.x, (1 < x <
- 255), and set the Subnet Mask to 255.255.255.0
-
- 5. Now select the "Gateway" tab and add 192.168.0.1 as your gateway under
- 'Gateway' and hit "Add".
-
- 6. Under the 'DNS Configuration' tab, make sure to put enter in a name for
- this machine and specify your official domain name. If you don't have
- your own domain, enter in the domain of your ISP. Next, you need to
- specify the DNS servers you plan on using.
-
- DHCP: No entries are required as this is configured dynamically via DHCP.
-
- STATIC: Add all of the DNS servers that your Linux MASQ server uses
- (usually found in /etc/resolv.conf). Usually these DNS servers are
- located at your ISP though you could be running either your own Caching
- or Authoritative DNS server on your Linux MASQ server as well. Again,
- setting up DNS services is beyond the scope of this HOWTO but it is
- covered by TrinityOS as well as the LDP's DNS HOWTO.
-
- Optionally, you can add any appropriate domain search suffixes as well.
- This allows users to simply type in the hostname of the destination
- computer instead of the fully qualified domain name (FQDN). This is
- similar to the PATH function for finding common Unix commands.
-
- 7. Leave all of the other settings alone as they are unless (even dangerous)
- if you don't know what you're doing.
-
- 8. Click 'OK' in all dialog boxes and restart your system.
-
- 9. As an initial test, Ping the Linux MASQ server to test the network
- connection: 'Start/Run', type: ping 192.168.0.1(This is only an INTERNAL
- LAN connection test, you might not be able to ping the outside world
- yet.) If you don't see "replies" to your PINGs, please verify your
- network configuration.
-
-10. You can optionally create a HOSTS file in the C:\Windows directory so
- that you can ping the "hostname" of the machines on your LAN without the
- need for a DNS server. There is an example called HOSTS.SAM in the C:\
- windows directory for an example.
-
-
------------------------------------------------------------------------------
-4.2. Configuring Windows NT
-
-
-
- 1. If you haven't installed your network card and adapter driver, do so now.
- Descriptions to perform this task is beyond the scope of this document.
-
- 2. Go to 'Control Panel' --> 'Network' --> Protocols
-
- 3. Add the TCP/IP Protocol and related Components from the 'Add Software'
- menu if you don't have TCP/IP service installed already.
-
- 4. Under 'Network Software and Adapter Cards' section, highlight the 'TCP/IP
- Protocol' in the 'Installed Network Software' selection box.
-
- 5. In 'TCP/IP Configuration', select the appropriate adapter, e.g. [1]Intel
- EtherExpress Pro/100+. Then set the IP Address to 192.168.0.x (1 < x <
- 255), then set the Subnet Mask to 255.255.255.0 and Default Gateway to
- 192.168.0.1.
-
- 6. Do not enable any of the following options (unless you know what you are
- doing):
-
- + 'Automatic DHCP Configuration' : Unless you have a DHCP server
- running on your network.
-
- + Put anything in the 'WINS Server' input areas : Unless you have setup
- one or more WINS servers.
-
- + Enable IP Forwardings : Unless you are routing on your NT machine and
- really -REALLY- know EXACTLY what you're doing.
-
-
- 7. Click 'DNS', fill in the appropriate information that your Linux host
- uses (usually found in /etc/resolv.conf) and then click 'OK' when you're
- done.
-
- 8. Click 'Advanced', be sure to DISABLE 'DNS for Windows Name Resolution'
- and 'Enable LMHOSTS lookup' unless you known what these options do. If
- you want to use a LMHOSTS file, it is stored in C:\winnt\system32\drivers
- \etc.
-
- 9. Click 'OK' on all dialog boxes and restart the system.
-
-10. As an initial test, ping the Linux MASQ server to test the network
- connection: 'File/Run', type: ping 192.168.0.1(This is only an INTERNAL
- LAN connection test, you you might not be able to ping the outside world
- yet.) If you don't see any "replies" to your PINGs, please verify your
- network configuration.
-
-
-
------------------------------------------------------------------------------
-
-4.3. Configuring Windows for Workgroup 3.11
-
-
-
- 1. If you haven't installed your network card and adapter driver, do so now.
- Descriptions to perform this task is beyond the scope of this document.
-
- 2. Install the TCP/IP 32b package if you haven't already.
-
- 3. In 'Main'/'Windows Setup'/'Network Setup', click on 'Drivers'.
-
- 4. Highlight 'Microsoft TCP/IP-32 3.11b' in the 'Network Drivers' section,
- click 'Setup'.
-
- 5. Set the IP Address to 192.168.0.x (1 < x < 255), then set the Subnet Mask
- to 255.255.255.0 and Default Gateway to 192.168.0.1
-
- 6. Do not enable any of the following options (unless you know what you are
- doing):
-
- + 'Automatic DHCP Configuration' : Unless you have a DHCP server
- running on your network.
-
- + Put anything in the 'WINS Server' input areas : Unless you have setup
- one or more WINS servers.
-
-
- 7. Click 'DNS', fill in the appropriate information your Linux host uses
- (usually found in /etc/resolv.conf). Then click 'OK' when you're done
- with it.
-
- 8. Click 'Advanced', check 'Enable DNS for Windows Name Resolution' and
- 'Enable LMHOSTS lookup' found in c:\windows.
-
- 9. Click 'OK' in all dialog boxes and restart the system.
-
-10. As an initial test, ping the linux box to test the network connection:
- 'File/Run', type: ping 192.168.0.1 (This is only an INTERNAL LAN
- connection test so you might not be able to ping the outside world yet.)
- If you don't see "replies" to your PINGs, please verify your network
- configuration.
-
-
------------------------------------------------------------------------------
-4.4. Configuring UNIX Based Systems
-
-
-
- 1. If you haven't installed your network card and either re-configured the
- network subsystem or recompiled your kernel with the appropriate adapter
- driver, do so now. Descriptions to perform this task is beyond the scope
- of this document but are covered in the Networking HOWTO.
-
- 2. Install TCP/IP networking, such as the net-tools package, if you don't
- have it already.
-
- 3. Set IPADDR to 192.168.0.x (1 < x < 255), then set NETMASK to
- 255.255.255.0, GATEWAY to 192.168.0.1, and BROADCAST to 192.168.0.255.
-
- + Redhat (Mandrake / TurboLinux / etc): You can edit the /etc/sysconfig
- /network-scripts/ifcfg-eth0 file, or simply do so through the Control
- Panel (Linuxconf).
-
- + Slackware: You need to edit the /etc/rc.d/rc.inet1 file to configure
- the network subsystem.
-
- + To Add: Debian, Suse, Caldera, etc. Please email dranch@trinnet.net
- if you can tell me what distro uses what files to configure the
- networking subsystem.
-
-
- Beyond this, most Linux distributions use significantly different network
- configuration mechanisms let alone other UNIXes such as SunOS, BSDi,
- Solaris, AIX, TruUnix, FreeBSD, etc.). Please refer to your specific UNIX
- documentation for more details.
-
- 4. Add your domain name service (DNS) and domain search suffix in /etc/
- resolv.conf and for the appropreiate UNIX versions, edit the /etc/
- nsswitch.conf file to enable DNS services.
-
- 5. You may also want to update your /etc/networks file depending on your
- version of UNIX and the system's settings.
-
- 6. Restart the appropriate services, or simply restart your system.
-
- 7. As an initial test, run the ping command: ping 192.168.0.1 to test the
- connection to your gateway machine. (This is only an INTERNAL LAN
- connection test, so you might not be able to ping the outside world yet.)
- If you don't see "replies" to your PINGs, please verify your network
- configuration.
-
-
-
------------------------------------------------------------------------------
-
-4.5. Configuring DOS using NCSA Telnet package
-
-
-
- 1. If you haven't installed your network card, do so now. Descriptions to
- perform this task is beyond the scope of this document.
-
- 2. Load the appropriate packet driver. For example: an NE2000 Ethernet card
- set for I/O port 300 and IRQ 10, would need to be issued nwpd 0x60 10
- 0x300
-
- 3. Make a new directory, and then unpack the NCSA Telnet package: pkunzip
- tel2308b.zip
-
- 4. Use a text editor to open the config.tel file
-
- 5. Set myip=192.168.0.x (1 < x < 255), and netmask=255.255.255.0
-
- 6. In this example, you should set hardware=packet, interrupt=10, ioaddr=60
-
- 7. You should have at least one individual machine specified as the gateway,
- i.e. the Linux host:
-
- +---------------------------------------------------------------+
- | name=default |
- | host=yourlinuxhostname |
- | hostip=192.168.0.1 |
- | gateway=1 |
- +---------------------------------------------------------------+
-
- 8. Have another specified as a domain name service:
-
- +---------------------------------------------------------------+
- | name=dns.domain.com ; hostip=123.123.123.123; nameserver=1|
- +---------------------------------------------------------------+
-
- Note: substitute the appropriate information about the DNS according what
- your Linux host uses
-
- 9. Save your config.tel file
-
-10. As an initial test, ping the Linux MASQ server to test the network
- connection: ping 192.168.0.1 If you don't receive any replies, please
- verify your network configuration.
-
-
-
------------------------------------------------------------------------------
-
-4.6. Configuring MacOS Based System Running MacTCP
-
- 1. If you haven't installed the appropriate driver software for your
- Ethernet adapter, do so now. Descriptions to perform this task is beyond
- the scope of this document.
-
- 2. Open the MacTCP control panel. Select the appropriate network driver
- (Ethernet, NOT EtherTalk) and click on the 'More...' button.
-
- 3. Under 'Obtain Address:', click 'Manually'.
-
- 4. Under 'IP Address:', select class C from the popup menu. Ignore the rest
- of the dialog box sections.
-
- 5. Fill in the appropriate information under 'Domain Name Server
- Information:'.
-
- 6. Under 'Gateway Address:', enter 192.168.0.1
-
- 7. Click 'OK' to save the settings. In the main window of the MacTCP control
- panel, enter the IP address of your Mac (192.168.0.x, 1 < x < 255) in the
- 'IP Address:' box.
-
- 8. Close the MacTCP control panel. If a dialog box pops up, notifying you to
- do so, then restart the system.
-
- 9. You may optionally ping the Linux box to test the network connection. If
- you have the freeware program MacTCP Watcher , click on the 'Ping'
- button, and enter the address of your Linux box (192.168.0.1) in the
- dialog window that pops up. (This is only an INTERNAL LAN connection
- test, you can't ping the outside world yet.) If you don't see "replies"
- to your PINGs, please verify your network configuration.
-
-10. You can optionally create a Hosts file in your System Folder so that you
- can use the hostnames of the machines on your LAN. The file should
- already exist in your System Folder, and should contain some
- (commented-out) sample entries which you can modify according to your
- needs.
-
-
-
------------------------------------------------------------------------------
-
-4.7. Configuring MacOS Based System Running Open Transport
-
-
-
- 1. If you haven't installed the appropriate driver software for your
- Ethernet adapter, do so now. Descriptions to perform this task is beyond
- the scope of this document.
-
- 2. Open the TCP/IP Control Panel and choose 'User Mode ...' from the Edit
- menu. Make sure the user mode is set to at least 'Advanced' and click the
- 'OK' button.
-
- 3. Choose 'Configurations...' from the File menu. Select your 'Default'
- configuration and click the 'Duplicate...' button. Enter 'IP Masq' (or
- something to let you know that this is a special configuration) in the
- 'Duplicate Configuration' dialog, it will probably say something like
- 'Default copy'. Then click the 'OK' button, and the 'Make Active' button
-
- 4. Select 'Ethernet' from the 'Connect via:' pop-up.
-
- 5. Select the appropriate item from the 'Configure:' pop-up. If you don't
- know which option to choose, you probably should re-select your 'Default'
- configuration and quit. I use 'Manually'.
-
- 6. Enter the IP address of your Mac (192.168.0.x, 1 < x < 255) in the 'IP
- Address:' box.
-
- 7. Enter 255.255.255.0 in the 'Subnet mask:' box.
-
- 8. Enter 192.168.0.1 in the 'Router address:' box.
-
- 9. Enter the IP addresses of your domain name servers in the 'Name server
- addr.:' box.
-
-10. Enter the name of your Internet domain (e.g. 'microsoft.com') in the
- 'Starting domain name' box under 'Implicit Search Path:'.
-
-11. The following procedures are optional. Incorrect values may cause erratic
- behavior. If you're not sure, it's probably better to leave them blank,
- unchecked and/or un-selected. Remove any information from those fields,
- if necessary. As far as I know, there is no way to use the TCP/IP dialogs
- to tell the system not to use a previously selected alternate "Hosts"
- file. If you know, I would be interested.
-
- Check the '802.3' if your network requires 802.3 frame types.
-
-12. Click the 'Options...' button to make sure that the TCP/IP is active. I
- use the 'Load only when needed' option. If you continuously run and quit
- TCP/IP applications without rebooting your machine, you may find that
- unchecking the 'Load only when needed' option will prevent/reduce the
- effects on your machine's memory management. With the item unchecked, the
- TCP/IP protocol stacks are always loaded and available for use. If
- checked, the TCP/IP stacks are automatically loaded when needed and
- un-loaded when not. It's the loading and unloading process that can cause
- your machine's memory to become fragmented.
-
-13. You may ping the Linux box to test the network connection. If you have
- the freeware program MacTCP Watcher, click on the 'Ping' button, and
- enter the address of your Linux box (192.168.0.1) in the dialog box that
- pops up. (This is only an INTERNAL LAN connection test, you can't ping
- the outside world yet.) If you don't see "replies" to your PINGs, please
- verify your network configuration.
-
-14. You can optionally create a Hosts file in your System Folder so that you
- can use the hostnames of the machines on your LAN. The file may or may
- not already exist in your System Folder. If so, it should contain some
- (commented-out) sample entries which you can modify according to your
- needs. If not, you can get a copy of the file from a system running
- MacTCP, or just create your own (it follows a subset of the Unix /etc/
- hosts file format, described on RFC1035). Once you've created the file,
- open the TCP/IP control panel, click on the 'Select Hosts File...'
- button, and open the Hosts file.
-
-15. Click the close box or choose 'Close' or 'Quit' from the File menu, and
- then click the 'Save' button to save the changes you have made.
-
-16. The changes take effect immediately, but rebooting the system won't hurt.
-
-
-
------------------------------------------------------------------------------
-
-4.8. Configuring Novell network using DNS
-
-
-
- 1. If you haven't installed the appropriate driver software for your
- Ethernet adapter, do so now. Descriptions to perform this task is beyond
- the scope of this document.
-
- 2. Downloaded tcpip16.exe from The Novell LanWorkPlace page
-
- 3. +---------------------------------------------------------------+
- |edit c:\nwclient\startnet.bat: (here is a copy of mine) |
- |SET NWLANGUAGE=ENGLISH |
- |LH LSL.COM |
- |LH KTC2000.COM |
- |LH IPXODI.COM |
- |LH tcpip |
- |LH VLM.EXE |
- |F: |
- +---------------------------------------------------------------+
-
- 4. +---------------------------------------------------------------------------+
- |edit c:\nwclient\net.cfg: (change link driver to yours i.e. NE2000) |
- |Link Driver KTC2000 |
- | Protocol IPX 0 ETHERNET_802.3 |
- | Frame ETHERNET_802.3 |
- | Frame Ethernet_II |
- | FRAME Ethernet_802.2 |
- | |
- |NetWare DOS Requester |
- | FIRST NETWORK DRIVE = F |
- | USE DEFAULTS = OFF |
- | VLM = CONN.VLM |
- | VLM = IPXNCP.VLM |
- | VLM = TRAN.VLM |
- | VLM = SECURITY.VLM |
- | VLM = NDS.VLM |
- | VLM = BIND.VLM |
- | VLM = NWP.VLM |
- | VLM = FIO.VLM |
- | VLM = GENERAL.VLM |
- | VLM = REDIR.VLM |
- | VLM = PRINT.VLM |
- | VLM = NETX.VLM |
- | |
- |Link Support |
- | Buffers 8 1500 |
- | MemPool 4096 |
- | |
- |Protocol TCPIP |
- | PATH SCRIPT C:\NET\SCRIPT |
- | PATH PROFILE C:\NET\PROFILE |
- | PATH LWP_CFG C:\NET\HSTACC |
- | PATH TCP_CFG C:\NET\TCP |
- | ip_address 192.168.0.xxx |
- | ip_router 192.168.0.1 |
- | |
- | |
- |Change the IP address in the above "ip_address" field (192.168.0.x, 1 < x |
- |< 255) and finally create c:\bin\resolv.cfg: |
- | |
- |SEARCH DNS HOSTS SEQUENTIAL |
- |NAMESERVER xxx.xxx.xxx.xxx |
- |NAMESERVER yyy.yyy.yyy.yyy |
- +---------------------------------------------------------------------------+
-
- 5. Now edit the above "NAMESERVER" entries and replace them with the correct
- IP addresses for your local DNS server.
-
- 6. Issue a ping command: ping 192.168.0.1 to test the connection to your
- gateway machine. (This is only an INTERNAL LAN connection test, you can't
- ping the outside world yet.) If you don't see "replies" to your PINGs,
- please verify your network configuration.
-
-
-
------------------------------------------------------------------------------
-
-4.9. Configuring OS/2 Warp
-
-
-
- 1. If you haven't installed the appropriate driver software for your
- Ethernet adapter, do so now. Descriptions to perform this task is beyond
- the scope of this document.
-
- 2. Install the TCP/IP protocol if you don't have it already.
-
- 3. Go to Programs/TCP/IP (LAN) / TCP/IP Settings
-
- 4. In 'Network', add your TCP/IP Address (192.168.0.x) and set your netmask
- (255.255.255.0)
-
- 5. Under 'Routing', press 'Add'. Set the Type to 'default' and type the IP
- Address of your Linux Box in the Field 'Router Address'. (192.168.0.1).
-
- 6. Set the same DNS (Nameserver) Address that your Linux host uses in
- 'Hosts'.
-
- 7. Close the TCP/IP control panel. Say yes to the following question(s).
-
- 8. Reboot your system
-
- 9. You may ping the Linux box to test the network configuration. Type 'ping
- 192.168.0.1' in a 'OS/2 Command prompt Window'. When ping packets are
- received all is ok.
-
-
-
------------------------------------------------------------------------------
-
-4.10. Configuring OS/400 on a IBM AS/400
-
-The descriptions to configure TCP/IP on OS/400 version V4R1M0 running on a AS
-/400 is beyond the scope of this document.
-
-1) To perform any communications configuration tasks on your AS/400, you must
-have the special authority of *IOSYSCFG (I/O System Configuration) defined in
-your user profile. You can check the characteristics of your user profile
-with the DSPUSRPRF command.
-
-2) Type GO CFGTCP command th reach the Configure TCP/IP menu.
-
-3) Select Option 2 - Work with TCP/IP Routes.
-
-4) Enter a 1 on the Opt field to add a route. * In Route Destination type *
-DFTROUTE * In Subnet Mask type *NONE * In Type of Service type *NORMAL * In
-Nex Hop type the address of your gataway (the Linux box)
------------------------------------------------------------------------------
-
-4.11. Configuring Other Systems
-
-The same logic should apply to setting up other platforms. Consult the
-sections above. If you're interested in writing about any of systems that
-have not been covered yet, please send a detail setup instruction to [mailto:
-ambrose@writeme.com] ambrose@writeme.com and [mailto:dranch@trinnet.net]
-dranch@trinnet.net.
------------------------------------------------------------------------------
-
-Chapter 5. Testing IP Masquerade
-
-Finally, it's time to give IP Masquerading an official try after all this
-hard work. If you haven't already rebooted your Linux box, do so to make sure
-the machines boots ok, executes the /etc/rc.d/rc.firewall ruleset, etc. Next,
-make sure that both the internal LAN connection and connection of your Linux
-hosts to the Internet is okay.
-
-Follow these -11- tests to make sure all aspects of your MASQ setup is
-running properly:
------------------------------------------------------------------------------
-
-5.1. Loading up the rc.firewall ruleset
-
-Step One: run the command "/etc/rc.d/rc.firewall".
-
-Does it load with some strange errors? Here are some exmaples and help to fix
-them:
-
- * Problem #1:
-
-
- +--------------------------------------------------------------------------------+
- |ip_tables, Using /lib/modules/2.4.2-2/kernel/net/ipv4/netfilter/ip_tables.o |
- |/lib/modules/2.4.2-2/kernel/net/ipv4/netfilter/ip_tables.o: init_module: Device |
- |or resource busy |
- |Hint: insmod errors can be caused by incorrect module parameters, including |
- |invalid IO or IRQ parameters |
- | |
- +--------------------------------------------------------------------------------+
-
- Run the command "/sbin/lsmod" and make sure the module "ipchains.o" is
- NOT installed. If it is installed, your machine (most likely Redhat-7.x
- based) is probably trying to load an IPCHAINS ruleset which is
- incompatible with IPTABLES.
-
- To disable this from happening in the future, run the command:
- +---------------------------------------------------------------+
- | chkconfig --level=2345 ipchains off |
- | |
- +---------------------------------------------------------------+
-
- To remove the "ipchains" module without rebooting, run the command:
- +---------------------------------------------------------------+
- | /sbin/rmmod ipchains |
- | |
- +---------------------------------------------------------------+
- and the re-try to load the rc.firewall ruleset.
-
- * Problem #2:
-
- +---------------------------------------------------------------+
- | . |
- | . |
- | Creating a DROP chain.. |
- | iptables v1.2.3: log-level `info' ambiguous |
- | . |
- | . |
- | |
- +---------------------------------------------------------------+
-
- Your version of IPTABLES it too old. You need to upgrade it with a newer
- version via an updated RPM, DEB, or via compiling up the source. You can
- get an updated version from your Linux distribution manufacturer or from
- the NetFilter WWW site. This is all covered in the Section 2.6 section.
-
- * Problem #3:
-
- +---------------------------------------------------------------+
- | No such file: |
- | |
- +---------------------------------------------------------------+
-
- Did you copy this rc.firewall file from a DOS machine? Load the
- rc.firewall file in a binary editor such as ViM (vim -b /etc/rc.d/
- rc.firewall) and make sure that every line is NOT finished with a ^M.
-
-
------------------------------------------------------------------------------
-5.2. Testing internal MASQ client PC connectivity
-
- * Step Two: Testing internal MASQ client PC connectivity
-
- From an internal MASQed computer, try pinging its local IP address (i.e.
- ping 192.168.0.10 ). This will verify that TCP/IP is correctly working on
- the local machine. Almost ALL modern operating systems have built-in
- support for the "ping" command. If this ping doesn't work, make sure that
- TCP/IP is correctly configured on the MASQed PC as described earlier in
- Chapter 4 of this HOWTO. The output should look something like the
- following (hit Control-C to abort the ping):
-
- ------------------------------------
- masq-client# ping 192.168.0.10
- PING 192.168.0.10 (192.168.0.10): 56 data bytes
- 64 bytes from 192.168.0.10: icmp_seq=0 ttl=255 time=0.8 ms
- 64 bytes from 192.168.0.10: icmp_seq=1 ttl=255 time=0.4 ms
- 64 bytes from 192.168.0.10: icmp_seq=2 ttl=255 time=0.4 ms
- 64 bytes from 192.168.0.10: icmp_seq=3 ttl=255 time=0.5 ms
- ^C
-
- --- 192.168.0.10 ping statistics ---
- 4 packets transmitted, 4 packets received, 0% packet loss
- round-trip min/avg/max = 0.4/0.5/0.8 ms
- ------------------------------------
-
-
------------------------------------------------------------------------------
-5.3. Testing internal MASQ client to MASQ server connectivity
-
- * Step Three: Testing internal MASQ client to MASQ server connectivity
-
- Next, from the same internal MASQed computer, try pinging the the IP
- address of the Linux MASQ server's INTERNAL interface (i.e. ping
- 192.168.0.1 ). This will verify that TCP/IP is correctly working on both
- the local and Linux MASQ machine. Almost ALL modern operating systems
- have built-in support for the "ping" command. If this ping doesn't work,
- make sure that TCP/IP is correctly configured on the MASQed Server as
- described by the various Network HOWTOs (URLs can be found in the
- requirements section for your 2.4.x kernel in Section 2.6, 2.2.x kernel
- in Section 2.7, or 2.0.x kernel in Section 2.8). The output should look
- something like the following (hit Control-C to abort the ping):
-
- ------------------------------------
- masq-client# ping 192.168.0.1
- PING 192.168.0.1 (192.168.0.1): 56 data bytes
- 64 bytes from 192.168.0.1: icmp_seq=0 ttl=255 time=0.8 ms
- 64 bytes from 192.168.0.1: icmp_seq=1 ttl=255 time=0.4 ms
- 64 bytes from 192.168.0.1: icmp_seq=2 ttl=255 time=0.4 ms
- 64 bytes from 192.168.0.1: icmp_seq=3 ttl=255 time=0.5 ms
- ^C
-
- --- 192.168.0.1 ping statistics ---
- 4 packets transmitted, 4 packets received, 0% packet loss
- round-trip min/avg/max = 0.4/0.5/0.8 ms
- ------------------------------------
-
- If the ping failed, check the network connection between the MASQ server
- and the PC. If it's a DIRECT Ethernet connection (no hub or switch), you
- MUST have a "Ethernet cross-over cable". These cables are common and can
- be found at any computer store. Without this cable, the NICs (network
- cards) will not give you a "LINK" light. If you are using a hub or
- switch, make sure the ports connected to the MASQ server and MASQed
- client machine have a LINK light. If they do and the pings STILL don't
- work or there is a lot of packet loss, try different ports on the hub/
- switch (it not all that uncommon to have hub/switch ports die). Finally,
- if things still don't work perfectly, try replacing each of the NICs in
- the machines. You would be surprised how many people I've helped have
- found that their NIC cards were going bad and caused them all kinds of
- grief.
-
-
-
------------------------------------------------------------------------------
-
-5.4. Testing internal MASQ server connectivity
-
- * Step Four: Testing internal MASQ server connectivity
-
- On the MASQ server, ping the internal IP address of the MASQ server's
- network interface card (i.e. ping 192.168.0.1). If this ping doesn't
- work, make sure that TCP/IP is correctly configured on the MASQed Server
- as described by the various Network HOWTOs (URLs can be found in the
- requirements section for your 2.4.x kernel in Section 2.6, 2.2.x kernel
- in Section 2.7, or 2.0.x kernel in Section 2.8). The output should look
- something like the following (hit Control-C to abort the ping):
-
- --------------------------------------
- masq-server# ping 192.168.0.1
- PING 192.168.0.1 (192.168.0.1): 56 data bytes
- 64 bytes from 192.168.0.1: icmp_seq=0 ttl=255 time=0.8 ms
- 64 bytes from 192.168.0.1: icmp_seq=1 ttl=255 time=0.4 ms
- 64 bytes from 192.168.0.1: icmp_seq=2 ttl=255 time=0.4 ms
- 64 bytes from 192.168.0.1: icmp_seq=3 ttl=255 time=0.5 ms
- ^C
-
- --- 192.168.0.1 ping statistics ---
- 4 packets transmitted, 4 packets received, 0% packet loss
- round-trip min/avg/max = 0.4/0.5/0.8 ms
- ---------------------------------------
-
-
------------------------------------------------------------------------------
-5.5. Testing internal MASQ server to MASQ client connectivity
-
- * Step Five: Testing internal MASQ server to MASQ client connectivity
-
- Next from MASQed server, try pinging the IP address of one of the
- internal MASQ client computers (i.e. ping 192.168.0.10 ). This will
- verify that TCP/IP is correctly working on both the local server machine
- and on the MASQ client machine. If this ping doesn't work, make sure that
- TCP/IP is correctly configured on the MASQed PC as described earlier in
- Chapter 4 of this HOWTO. Also be sure that the cabling is correct
- (Ethernet: the NICs connecting the internal MASQ PC and the MASQ server
- have the "link" light lit up). If the ping does work, the output should
- look something like the following (hit Control-C to abort the ping):
-
- ------------------------------------
- masq-server# ping 192.168.0.10
- PING 192.168.0.10 (192.168.0.10): 56 data bytes
- 64 bytes from 192.168.0.10: icmp_seq=0 ttl=255 time=0.8 ms
- 64 bytes from 192.168.0.10: icmp_seq=1 ttl=255 time=0.4 ms
- 64 bytes from 192.168.0.10: icmp_seq=2 ttl=255 time=0.4 ms
- 64 bytes from 192.168.0.10: icmp_seq=3 ttl=255 time=0.5 ms
- ^C
-
- --- 192.168.0.10 ping statistics ---
- 4 packets transmitted, 4 packets received, 0% packet loss
- round-trip min/avg/max = 0.4/0.5/0.8 ms
- ------------------------------------
-
-
------------------------------------------------------------------------------
-5.6. Testing External MASQ server Internet connectivity
-
- * Step Six: Testing external MASQ server to Internet connectivity
-
- From the MASQ server, ping the external IP address of the MASQ server's
- EXTERNAL network interface that is connected to the Internet. This
- address might be a Ethernet interface, a PPP interface, etc. connection
- to your ISP. If you don't know what this external IP address is, run the
- Linux command "/sbin/ifconfig" on the MASQ server itself to get the
- Internet address. The output should look something like the following (we
- are looking for the IP address of eth0):
-
- ------------------------------------
- eth0 Link encap:Ethernet HWaddr 00:08:C7:A4:CC:5B
- inet addr:12.13.14.15 Bcast:12.13.14.255 Mask:255.255.255.0
- UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
- RX packets:6108459 errors:0 dropped:0 overruns:0 frame:0
- TX packets:5422798 errors:8 dropped:0 overruns:0 carrier:8
- collisions:4675 txqueuelen:100
- Interrupt:11 Base address:0xfcf0
- ------------------------------------
-
- As you can see from the above, the external IP address is "12.13.14.15"
- for this example. So, now that you have your IP address after running the
- "ipconfig" command, ping your external IP address. This will confirm that
- the MASQ server has full network connectivity. The output should look
- something like the following (hit Control-C to abort the ping):
-
- -------------------------------------
- masq-server# ping 12.13.14.15
- PING 12.13.14.15 (12.13.14.15): 56 data bytes
- 64 bytes from 12.13.14.15: icmp_seq=0 ttl=255 time=0.8 ms
- 64 bytes from 12.13.14.15: icmp_seq=1 ttl=255 time=0.4 ms
- 64 bytes from 12.13.14.15: icmp_seq=2 ttl=255 time=0.4 ms
- 64 bytes from 12.13.14.15: icmp_seq=3 ttl=255 time=0.5 ms
- ^C
-
- --- 12.13.14.15 ping statistics ---
- 4 packets transmitted, 4 packets received, 0% packet loss
- round-trip min/avg/max = 0.4/0.5/0.8 ms
- -------------------------------------
-
- If either of these tests doesn't work, you need to go back and double
- check your network cabling and verify that the two network interfaces on
- the MASQ server are seen in "dmesg". An example of this output would be
- the following towards the END of the "dmesg" command:
-
- -------------------------------------
- .
- .
- PPP: version 2.3.7 (demand dialling)
- TCP compression code copyright 1989 Regents of the University of California
- PPP line discipline registered.
- 3c59x.c:v0.99H 11/17/98 Donald Becker
- http://cesdis.gsfc.nasa.gov/linux/drivers/
- vortex.html
- eth0: 3Com 3c905 Boomerang 100baseTx at 0xfe80, 00:60:08:a7:4e:0e, IRQ 9
- 8K word-wide RAM 3:5 Rx:Tx split, autoselect/MII interface.
- MII transceiver found at address 24, status 786f.
- Enabling bus-master transmits and whole-frame receives.
- eth1: 3Com 3c905 Boomerang 100baseTx at 0xfd80, 00:60:97:92:69:f8, IRQ 9
- 8K word-wide RAM 3:5 Rx:Tx split, autoselect/MII interface.
- MII transceiver found at address 24, status 7849.
- Enabling bus-master transmits and whole-frame receives.
- Partition check:
- sda: sda1 sda2 < sda5 sda6 sda7 sda8 >
- sdb:
- .
- .
- -------------------------------------
-
- Also be sure that the cabling is correct (Ethernet: the NICs connecting
- the external MASQ server to your ISP has the "link" light lit up).
- Finally, make sure that TCP/IP is correctly configured on the MASQed
- Server as described by the various Network HOWTOs (URLs can be found in
- the requirements section for your 2.4.x kernel in Section 2.6, 2.2.x
- kernel in Section 2.7, or 2.0.x kernel in Section 2.8).
-
-
------------------------------------------------------------------------------
-5.7. Testing internal MASQ client to external MASQ server connectivity
-
-
-
- * Step Seven: Testing internal MASQ client to external MASQ server
- connectivity
-
- From an internal MASQed computer, ping the IP address of the MASQ
- server's EXTERNAL TCP/IP address obtained in Step FIVE above. This
- address could be from your Ethernet, PPP, etc. interface which is
- ultimately the address connected to your ISP. This ping test will prove
- that Linux masquerading (ICMP Masquerading specifically) and IP
- forwarding is working.
-
- If everthing thing is working correctly, the output should look something
- like the following (hit Control-C to abort the ping):
-
- -------------------------------------
- masq-client# ping 12.13.14.15
- PING 12.13.14.15 (12.13.14.15): 56 data bytes
- 64 bytes from 12.13.14.15: icmp_seq=0 ttl=255 time=0.8 ms
- 64 bytes from 12.13.14.15: icmp_seq=1 ttl=255 time=0.4 ms
- 64 bytes from 12.13.14.15: icmp_seq=2 ttl=255 time=0.4 ms
- 64 bytes from 12.13.14.15: icmp_seq=3 ttl=255 time=0.5 ms
- ^C
-
- --- 12.13.14.15 ping statistics ---
- 4 packets transmitted, 4 packets received, 0% packet loss
- round-trip min/avg/max = 0.4/0.5/0.8 ms
- -------------------------------------
-
- If this test doesn't work, first make sure that the "Default Gateway" on
- the MASQed PC is pointing to the IP address on the MASQ -SERVERs-
- INTERNAL NIC. Also double check that the /etc/rc.d/rc.firewall script was
- run without any errors. Just as a test, try re-running the /etc/rc.d/
- rc.firewall script now to see if it runs OK. Also, though most kernels
- support it by default, make sure that you enabled "ICMP Masquerading" in
- the kernel comfiguration and "IP Forwarding" in your /etc/rc.d/
- rc.firewall script.
-
- If you still can't get things to work, take a look at the output from the
- following commands run on the Linux MASQ SERVER:
-
- + "ifconfig" : Make sure the interface for your Internet connection (be
- it ppp0, eth0, etc.) is UP and you have the correct IP address for
- the Internet connection. An example of this output is shown in STEP
- FIVE above.
-
- + "netstat -rn" : Make sure your default gateway (the column with an IP
- address in the Gateway column) is set. An example of this output
- might look like:
- -------------------------------------
- masq-server# netstat -rn
- Kernel IP routing table
- Destination Gateway Genmask Flags MSS Window irtt Iface
- 192.168.0.1 0.0.0.0 255.255.255.255 UH 0 16384 0 eth1
- 12.13.14.15 0.0.0.0 255.255.255.255 UH 0 16384 0 eth0
- 12.13.14.0 0.0.0.0 255.255.255.0 U 0 0 0 eth0
- 192.168.0.0 0.0.0.0 255.255.255.0 U 0 0 0 eth1
- 127.0.0.0 0.0.0.0 255.0.0.0 U 0 16384 0 lo
- 0.0.0.0 12.13.14.1 0.0.0.0 UG 0 16384 0 eth0
- -------------------------------------
- Notice the very LAST line that starts with 0.0.0.0? Notice that it
- also has an IP address in the "Gateway" field? You should specify an
- IP address for your specific setup in that field (this is typically
- done automatically when your Internet connection is enabled).
-
- + "cat /proc/sys/net/ipv4/ip_forward" : Make sure it says "1" so that
- Linux forwarding is enabled
-
- + Run the command "/sbin/ipchains -n -L" for 2.2.x users or "/sbin/
- ipfwadm -F -l" for 2.0.x users. Specifically, look for the FORWARDing
- section to make sure you have MASQ enabled. An example of an IPCHAINS
- output might look like for users using the Simple rc.firewall
- ruleset:
- ------------------------------------
- .
- .
- Chain forward (policy REJECT):
- target prot opt source destination ports
- MASQ all ------ 192.168.0.0/24 0.0.0.0/0 n/a
- ACCEPT all ----l- 0.0.0.0/0 0.0.0.0/0 n/a
- .
- .
- ------------------------------------
-
-
-
-
-
------------------------------------------------------------------------------
-
-5.8. Testing external MASQ ICMP forwarding
-
-
-
- * Step Eight: Testing external MASQ ICMP forwarding
-
- From an internal MASQed computer, ping a static TCP/IP address (NOT a
- machine by DNS name) out on the Internet (i.e. ping 152.2.210.81 (this
- technically the DNS name "metalab.unc.edu" which is home of MetaLabs'
- Linux Archive). If this works, it should look something like the result
- below and this ultimately shows that ICMP Masquerading is working
- properly. (hit Control-C to abort the ping):
-
- -------------------------------------
- masq-client# ping 152.2.210.81
-
- PING 12.13.14.15 (152.2.210.81): 56 data bytes
- 64 bytes from 152.2.210.81: icmp_seq=0 ttl=255 time=133.4 ms
- 64 bytes from 152.2.210.81: icmp_seq=1 ttl=255 time=132.5 ms
- 64 bytes from 152.2.210.81: icmp_seq=2 ttl=255 time=128.8 ms
- 64 bytes from 152.2.210.81: icmp_seq=3 ttl=255 time=132.2 ms
- ^C
-
- --- 152.2.210.81 ping statistics ---
- 4 packets transmitted, 4 packets received, 0% packet loss
- round-trip min/avg/max = 128.8/131.7/133.4 ms
- -------------------------------------
-
- If this didn't work, again check your Internet connection. Make sure that
- the MASQ server itself can ping this address. If this works from the MASQ
- server, make sure you are using the simple rc.firewall ruleset and that
- you have ICMP Masqurading compiled into the Linux kernel.
-
- Finally, make sure that the ruleset which enables IP MASQ is pointing to
- the correct EXTERNAL interface. PPPoE users should use the MASQ servers's
- logical PPP interface such as "ppp0" and /NOT/ the physical external
- interface like "eth0".
-
-
-
------------------------------------------------------------------------------
-
-5.9. Testing MASQ functionality without DNS
-
-
-
- * Step Nine: Testing MASQ functionality without DNS
-
- Now try TELNETing to a remote IP address (i.e. telnet 152.2.210.81 ( this
- is technically the DNS name "metalab.unc.edu"). It might take a few
- seconds to get a login prompt since this is a VERY busy server. Did you
- get a login prompt like shown below? If so, it means that TCP
- Masquerading is running OK. If not, try TELNETing to some other hosts you
- think will support TELNET like 198.182.196.55 (www.linux.org). If this
- still doesn't work, make sure you are using the simple rc.firewall
- ruleset for this test. An example of this output might look like (hit
- Control-D to exit out of the TELNET):
- --------------------------------
- masq-client# telnet 152.2.210.81
- Trying 152.2.210.81...
- Connected to 152.2.210.81.
- Escape character is '^]'.
-
-
- SunOS 5.7
-
-
- ******************** Welcome to MetaLab.unc.edu *******************
-
- To login to MetaLab as a user, connect to login.metalab.unc.edu.
- This machine does not allow public telnet logins.
-
- login: Connection closed by foreign host.
- --------------------------------
-
-
-
------------------------------------------------------------------------------
-
-5.10. Testing MASQ functionality with DNS resolution
-
-
-
- * Step Ten: Testing MASQ functionality with DNS resolution
-
- Now try TELNETing to a remote machine by DNS name (i.e. "telnet
- metalab.unc.edu" (IP address 152.2.210.81). If this works, the output
- should look like something below. With this test, this shows that
- UDP-based DNS is working fine.
-
- --------------------------------
- masq-client# telnet MetaLab.unc.edu
- Trying 152.2.210.81...
- Connected to 152.2.210.81.
- Escape character is '^]'.
-
-
- SunOS 5.7
-
-
- ******************** Welcome to MetaLab.unc.edu *******************
-
- To login to MetaLab as a user, connect to login.metalab.unc.edu.
- This machine does not allow public telnet logins.
-
- login: Connection closed by foreign host.
- --------------------------------
-
- If this did not work, but Step EIGHT did work, make sure that you have
- one or more valid DNS servers configured on each of the MASQ CLIENT
- computer(s) as shown in Chapter 4. Please note that these DNS servers
- will typically be your ISP's DNS servers and NOT your local MASQ server.
- Some people might later choose to setup their OWN DNS servers but this is
- beyond the scope of this HOWTO.
-
-
-
------------------------------------------------------------------------------
-
-5.11. Testing more MASQ functionality with DNS
-
-
-
- * Step Eleven: Testing more MASQ functionality with DNS
-
- As a last test, try browsing some 'INTERNET' WWW sites on one of your
- MASQ Client machines, and see if you can reach them. For example, access
- the Linux Documentation Project site at [http://www.tldp.org] http://
- www.tldp.org. If you are successful in bringing up that page, you can be
- fairly certain that everything is working FINE! If some WWW or FTP sites
- have problems, where other sites seem to work just fine, see the next
- step for more ideas.
-
- If you see The Linux Documentation Project homepage, then
- CONGRATULATIONS! It's working! If the WWW site comes up correctly, then
- all other standard network tools such as PING, TELNET, SSH, and with
- their related IP MASQ modules loaded: FTP, Real Audio, IRC DCCs, Quake I/
- II/III, CuSeeme, VDOLive, etc. should work fine too! If FTP, IRC,
- RealAudio, Quake I/II/III, etc. aren't working or are performing poorly,
- verify that their associated Masquerading modules are loaded by running
- "lsmod" and also be sure you are loading the module with any non-default
- server ports. If you don't see your needed module, make sure your /etc/
- rc.d/rc.firewall script is loading them (i.e. remove the # character for
- a given IP MASQ module).
-
-
-
------------------------------------------------------------------------------
-
-5.12. Any remaining functional, performance, etc. issues...
-
-
-
- * Step Twelve: Any remaining functional, performance, etc. issues...
-
- If your system passes all of the above tests, but functionality tests
- like WWW browsing, FTP, and other types of traffic aren't reliable or are
- slow, I recommend that you read the FAQ section of this HOWTO..
- specifically the Section 7.15 FAQ entry. There might be other items in
- the FAQ section that will also help you as they have helped many other
- users in the past.
-
-
-
------------------------------------------------------------------------------
-
-Chapter 6. Other IP Masquerade Issues and Software Support
-
-6.1. Problems with IP Masquerade
-
-Some TCP/IP application protocols will not currently work with Linux IP
-Masquerading because they either assume things about port numbers or encode
-TCP/IP addresses and/or port numbers in their data stream. These latter
-protocols need specific proxies or IP MASQ modules built into the
-masquerading code to make them work.
------------------------------------------------------------------------------
-
-6.2. Incoming services
-
-By default, Linux IP Masquerading cannot handle incoming services at all but
-there are a few ways that would allow this.
-
-If you do not require high levels of security, then you can simply forward or
-redirect IP ports. There are various ways to perform this, though the most
-stable method is to use IPPORTFW. For more information, please see Section
-6.7.
-
-If you wish to have some level of authorization on incoming connections, then
-you will need to either configure TCP-wrappers or Xinetd to allow only
-specific IP addresses to pass. The TIS Firewall Toolkit is a good place to
-look for tools and information.
-
-More details on incoming security can be found in the [http://
-www.ecst.csuchico.edu/~dranch/LINUX/index-linux.html#TrinityOS] TrinityOS
-document and at IP Masquerade Resource.
------------------------------------------------------------------------------
-
-6.3. Supported Client Software and Other Setup Notes
-
-"** The Linux Masquerade Application list has a lot of good information
-regarding applications that work through Linux IP masquerading. This site was
-recently taken over by Steve Grevemeyer, who implemented it with a full
-database backend. It's a great resource! "
-
-Generally, any application that uses standard TCP and UDP should work. If you
-have any suggestion, hints, etc., please see the [http://ipmasq.webhop.net/]
-IP Masquerade Resource for more details.
------------------------------------------------------------------------------
-
-6.3.1. Network Clients that -Work- with IP Masquerade
-
-General Clients:
-
-Archie
- all supported platforms, file searching client (not all archie clients
- are supported)
-
-FTP
- all supported platforms, with the ip_masq_ftp.o kernel module for active
- FTP connections.
-
-Gopher client
- all supported platforms
-
-HTTP
- all supported platforms, WWW surfing
-
-IRC
- all IRC clients on various supported platforms, DCC is supported via the
- ip_masq_irc.o module
-
-NNTP (USENET)
- all supported platforms, USENET news client
-
-PING
- all platforms, with ICMP Masquerading kernel option
-
-POP3
- all supported platforms, email clients
-
-SSH
- all supported platforms, Secure TELNET/FTP clients
-
-SMTP
- all supported platforms, email servers like Sendmail, Qmail, PostFix,
- etc.
-
-TELNET
- all supported platforms, remote session
-
-TRACEROUTE
- UNIX and Windows based platforms, some variations may not work
-
-VRML
- Windows(possibly all supported platforms), virtual reality surfing
-
-WAIS client
- all supported platforms
-
-
-Multimedia and Communication Clients:
-
-
-
-All H.323 programs
- - MS Netmeeting, Intel Internet Phone Beta , and other H.323 applications
- - There are now two solutions to accomplish this through IPMASQed
- connections:
-
- There is a stable BETA 2.2.x kernel module available on the [http://
- ipmasq.webhop.net] MASQ WWW site or at [http://www.coritel.it/projects/
- nat/implementation.htm] http://www.coritel.it/projects/nat/
- implementation.htm to work with Microsoft Netmeeting v3.x code on 2.2.x
- kernels. There is also another module version on the MASQ WWW site
- specifically for Netmeeting 2.x with 2.0.x kernels, but this does not
- support Netmeeting v3.x.
-
- Another commercial solution is the Equivalence's PhonePatch H.323
- gateway.
-
-
-Alpha Worlds
- Windows, Client-Server 3D chat program
-
-CU-SeeMe
- all supported platforms, with the ip_masq_cuseeme module loaded, please
- see Section 6.8 for more details.
-
-ICQ
- all supported clients. Requires the Linux kernel to be either compiled
- with PORTFW support, have the ip_masq_icq module (2.2.x and 2.0.x only),
- or have a SOCKS proxy running. A full description of this configuration
- is in Section 6.9.
-
-Internet Phone 3.2
- Windows, Peer-to-peer audio communications, users can reach you only if
- you initiate the call, but those users cannot call you without a specific
- port forwarding setup. See Section 6.7for more details.
-
-Internet Wave Player
- Windows, network streaming audio
-
-Powwow
- Windows, Peer-to-peer Text audio whiteboard communications, users can
- reach you only if you initiate the call, but those users cannot call you
- without a specific port forwarding setup. See Section 6.7for more
- details.
-
-Real Audio Player
- Windows, network streaming audio, higher quality available with the
- ip_masq_raudio UDP module
-
-True Speech Player 1.1b
- Windows, network streaming audio
-
-VDOLive
- Windows, with the ip_masq_vdolive patch
-
-Worlds Chat 0.9a
- Windows, Client-Server 3D chat program
-
-
-Games - See Section 6.10for more details on the LooseUDP patch
-
-Battle.net
- Works but requires TCP ports 116, 118 and UDP port 6112 IPPORTFWed to the
- client game machine. See Section 6.7for more details. Please note that
- FSGS and Bnetd servers still require IPPORTFW because they have not been
- re-written to be NAT-friendly.
-
-BattleZone 1.4
- Works with LooseUDP patch and new NAT-friendly -- email [mailto:
- dranch@trinnet.net] David Ranch for the .DLLs from Activision
-
-Dark Reign 1.4
- Works with LooseUDP patch or requires TCP ports 116 and 118 and UDP port
- 6112 IPPORTFWed to the game machine. See Section 6.7for more details.
-
-Diablo
- Works with LooseUDP patch or requires TCP ports 116 and 118 and UDP port
- 6112 IPPORTFWed to the game machine. Newer versions of Diablo use only
- TCP port 6112 and UDP port 6112. See Section 6.7for more details.
-
-Heavy Gear 2
- Works with LooseUDP patch or requires TCP ports 116 and 118 and UDP port
- 6112 IPPORTFWed to the game machine. See Section 6.7for more details.
-
-Quake I/II/III
- Works right out of the box but requires the ip_masq_quake module if there
- are more than one Quake I/II/III player behind a MASQ box. Also, this
- module only supports Quake I and QuakeWorld by default. If you need to
- support Quake II or non-default server ports, please see the module
- install section of Section 3.4.3 and Section 3.4.2 rulesets.
-
-StarCraft
- Works with the LooseUDP patch, IPPORTFWing TCP, and UDP ports 6112 to the
- internal MASQed game machine. See Section 6.7for more details.
-
-WorldCraft
- Works with LooseUDP patch
-
-
-Other Clients:
-
-Linux net-acct package
- Linux, network administration-account package
-
-NCSA Telnet 2.3.08
- DOS, a suite containing telnet, ftp, ping, etc.
-
-PC-anywhere for Windows
- MS-Windows remotely controls a PC over TCP/IP, but only works if it is a
- client, but not a host without a specific port forwarding setup. See
- Section 6.7for more details.
-
-Socket Watch
- uses NTP - network time protocol
-
-
------------------------------------------------------------------------------
-6.3.2. Clients that do not have full support in IP MASQ:
-
-Intel Streaming Media Viewer Beta 1
- Cannot connect to server
-
-Netscape CoolTalk
- Cannot connect to opposite side
-
-WebPhone
- Cannot work at present (it makes invalid assumptions about addresses).
-
-
------------------------------------------------------------------------------
-6.4. Stronger firewall rulesets to run after initial testing
-
-6.4.1. Stronger IP Firewall (IPTABLES) rulesets
-
-
-+---------------------------------------------------------------------------------+
-|#!/bin/sh |
-|# |
-|# rc.firewall-2.4-stronger |
-|# |
-|FWVER=0.80s |
-| |
-|# An example of a stronger IPTABLES firewall with IP Masquerade |
-|# support for 2.4.x kernels. |
-|# |
-|# Log: |
-|# |
-|# 0.80s - Added a DISABLED ip_nat_irc kernel module section, changed the |
-|# default of the ip_conntrack_irc to NOT load by default, and |
-|# added additional kernel module comments |
-|# 0.79s - ruleset now uses modprobe instead of insmod |
-|# 0.78s - REJECT is not a legal policy yet; back to DROP |
-|# 0.77s - Changed the default block behavior to REJECT not DROP |
-|# 0.76s - Added a comment about the OPTIONAL WWW ruleset and a comment |
-|# where to put optional PORTFW commands |
-|# 0.75s - Added clarification that PPPoE users need to use |
-|# "ppp0" instead of "eth0" for their external interface |
-|# 0.74s - Changed the EXTIP command to work on NON-English distros |
-|# 0.73s - Added comments in the output section that DHCPd is optional |
-|# and changed the default settings to disabled |
-|# 0.72s - Changed the filter from the INTNET to the INTIP to be |
-|# stateful; moved the command VARs to the top and made the |
-|# rest of the script to use them |
-|# 0.70s - Added a disabled examples for allowing internal DHCP |
-|# and external WWW access to the server |
-|# 0.63s - Added support for the IRC module |
-|# 0.62s - Initial version based upon the basic 2.4.x rc.firewall |
-| |
-| |
-|echo -e "\nLoading STRONGER rc.firewall - version $FWVER..\n" |
-| |
-| |
-|# The location of various iptables and other shell programs |
-|# |
-|# If your Linux distribution came with a copy of iptables, most |
-|# likely it is located in /sbin. If you manually compiled |
-|# iptables, the default location is in /usr/local/sbin |
-|# |
-|# ** Please use the "whereis iptables" command to figure out |
-|# ** where your copy is and change the path below to reflect |
-|# ** your setup |
-|# |
-|#IPTABLES=/sbin/iptables |
-|IPTABLES=/usr/local/sbin/iptables |
-|# |
-|LSMOD=/sbin/lsmod |
-|DEPMOD=/sbin/depmod |
-|MODPROBE=/sbin/modprobe |
-|GREP=/bin/grep |
-|AWK=/bin/awk |
-|SED=/bin/sed |
-|IFCONFIG=/sbin/ifconfig |
-| |
-| |
-|#Setting the EXTERNAL and INTERNAL interfaces for the network |
-|# |
-|# Each IP Masquerade network needs to have at least one |
-|# external and one internal network. The external network |
-|# is where the natting will occur and the internal network |
-|# should preferably be addressed with a RFC1918 private address |
-|# scheme. |
-|# |
-|# For this example, "eth0" is external and "eth1" is internal" |
-|# |
-|# NOTE: If this doesnt EXACTLY fit your configuration, you must |
-|# change the EXTIF or INTIF variables above. For example: |
-|# |
-|# If you are a PPPoE or analog modem user: |
-|# |
-|# EXTIF="ppp0" |
-|# |
-|EXTIF="eth0" |
-|INTIF="eth1" |
-|echo " External Interface: $EXTIF" |
-|echo " Internal Interface: $INTIF" |
-|echo " ---" |
-| |
-|# Specify your Static IP address here or let the script take care of it |
-|# for you. |
-|# |
-|# If you prefer to use STATIC addresses in your firewalls, un-# out the |
-|# static example below and # out the dynamic line. If you don't care, |
-|# just leave this section alone. |
-|# |
-|# If you have a DYNAMIC IP address, the ruleset already takes care of |
-|# this for you. Please note that the different single and double quote |
-|# characters and the script MATTER. |
-|# |
-|# |
-|# DHCP users: |
-|# ----------- |
-|# If you get your TCP/IP address via DHCP, **you will need ** to enable the |
-|# #ed out command below underneath the PPP section AND replace the word |
-|# "eth0" with the name of your EXTERNAL Internet connection (ppp0, ippp0, |
-|# etc) on the lines for "ppp-ip" and "extip". You should also note that the |
-|# DHCP server can and will change IP addresses on you. To deal with this, |
-|# users should configure their DHCP client to re-run the rc.firewall ruleset |
-|# everytime the DHCP lease is renewed. |
-|# |
-|# NOTE #1: Some DHCP clients like the original "pump" (the newer |
-|# versions have been fixed) did NOT have the ability to run |
-|# scripts after a lease-renew. Because of this, you need to |
-|# replace it with something like "dhcpcd" or "dhclient". |
-|# |
-|# NOTE #2: The syntax for "dhcpcd" has changed in recent versions. |
-|# |
-|# Older versions used syntax like: |
-|# dhcpcd -c /etc/rc.d/rc.firewall eth0 |
-|# |
-|# Newer versions execute a file called /etc/dhcpc/dhcpcd-eth0.exe |
-|# |
-|# NOTE #3: For Pump users, put the following line in /etc/pump.conf: |
-|# |
-|# script /etc/rc.d/rc.firewall |
-|# |
-|# PPP users: |
-|# ---------- |
-|# If you aren't already aware, the /etc/ppp/ip-up script is always run when |
-|# a PPP connection comes up. Because of this, we can make the ruleset go and |
-|# get the new PPP IP address and update the strong firewall ruleset. |
-|# |
-|# If the /etc/ppp/ip-up file already exists, you should edit it and add a line |
-|# containing "/etc/rc.d/rc.firewall" near the end of the file. |
-|# |
-|# If you don't already have a /etc/ppp/ip-up sccript, you need to create the |
-|# following link to run the /etc/rc.d/rc.firewall script. |
-|# |
-|# ln -s /etc/rc.d/rc.firewall /etc/ppp/ip-up |
-|# |
-|# * You then want to enable the #ed out shell command below * |
-|# |
-|# |
-|# Determine the external IP automatically: |
-|# ---------------------------------------- |
-|# |
-|# The following line will determine your external IP address. This |
-|# line is somewhat complex and confusing but it will also work for |
-|# all NON-English Linux distributions: |
-|# |
-|EXTIP="`$IFCONFIG $EXTIF | $AWK \ |
-| /$EXTIF/'{next}//{split($0,a,":");split(a[2],a," ");print a[1];exit}'`" |
-| |
-| |
-|# For users who wish to use STATIC IP addresses: |
-|# |
-|# # out the EXTIP line above and un-# out the EXTIP line below |
-|# |
-|#EXTIP="your.static.PPP.address" |
-|echo " External IP: $EXTIP" |
-|echo " ---" |
-| |
-| |
-|# Assign the internal TCP/IP network and IP address |
-|INTNET="192.168.1.0/24" |
-|INTIP="192.168.1.1/24" |
-|echo " Internal Network: $INTNET" |
-|echo " Internal IP: $INTIP" |
-|echo " ---" |
-| |
-| |
-| |
-| |
-|# Setting a few other local variables |
-|# |
-|UNIVERSE="0.0.0.0/0" |
-| |
-|#====================================================================== |
-|#== No editing beyond this line is required for initial MASQ testing == |
-| |
-|# Need to verify that all modules have all required dependencies |
-|# |
-|echo " - Verifying that all kernel modules are ok" |
-|$DEPMOD -a |
-| |
-|echo -en " Loading kernel modules: " |
-| |
-|# With the new IPTABLES code, the core MASQ functionality is now either |
-|# modular or compiled into the kernel. This HOWTO shows ALL IPTABLES |
-|# options as MODULES. If your kernel is compiled correctly, there is |
-|# NO need to load the kernel modules manually. |
-|# |
-|# NOTE: The following items are listed ONLY for informational reasons. |
-|# There is no reason to manual load these modules unless your |
-|# kernel is either mis-configured or you intentionally disabled |
-|# the kernel module autoloader. |
-|# |
-| |
-|# Upon the commands of starting up IP Masq on the server, the |
-|# following kernel modules will be automatically loaded: |
-|# |
-|# NOTE: Only load the IP MASQ modules you need. All current IP MASQ |
-|# modules are shown below but are commented out from loading. |
-|# =============================================================== |
-| |
-|#Load the main body of the IPTABLES module - "ip_tables" |
-|# - Loaded automatically when the "iptables" command is invoked |
-|# |
-|# - Loaded manually to clean up kernel auto-loading timing issues |
-|# |
-|echo -en "ip_tables, " |
-|# |
-|#Verify the module isn't loaded. If it is, skip it |
-|# |
-|if [ -z "` $LSMOD | $GREP ip_tables | $AWK {'print $1'} `" ]; then |
-| $MODPROBE ip_tables |
-|fi |
-| |
-| |
-|#Load the IPTABLES filtering module - "iptable_filter" |
-|# |
-|# - Loaded automatically when filter policies are activated |
-| |
-| |
-|#Load the stateful connection tracking framework - "ip_conntrack" |
-|# |
-|# The conntrack module in itself does nothing without other specific |
-|# conntrack modules being loaded afterwards such as the "ip_conntrack_ftp" |
-|# module |
-|# |
-|# - This module is loaded automatically when MASQ functionality is |
-|# enabled |
-|# |
-|# - Loaded manually to clean up kernel auto-loading timing issues |
-|# |
-|echo -en "ip_conntrack, " |
-|# |
-|#Verify the module isn't loaded. If it is, skip it |
-|# |
-|if [ -z "` $LSMOD | $GREP ip_conntrack | $AWK {'print $1'} `" ]; then |
-| $MODPROBE ip_conntrack |
-|fi |
-| |
-| |
-|#Load the FTP tracking mechanism for full FTP tracking |
-|# |
-|# Enabled by default -- insert a "#" on the next line to deactivate |
-|# |
-|echo -e "ip_conntrack_ftp, " |
-|# |
-|#Verify the module isn't loaded. If it is, skip it |
-|# |
-|if [ -z "` $LSMOD | $GREP ip_conntrack_ftp | $AWK {'print $1'} `" ]; then |
-| $MODPROBE ip_conntrack_ftp |
-|fi |
-| |
-| |
-|#Load the IRC tracking mechanism for full IRC tracking |
-|# |
-|# Disabled by default -- insert a "#" on the next few lines to activate |
-|# |
-|# echo -en " ip_conntrack_irc, " |
-|# |
-|#Verify the module isn't loaded. If it is, skip it |
-|# |
-|# if [ -z "` $LSMOD | $GREP ip_conntrack_irc | $AWK {'print $1'} `" ]; then |
-|# $MODPROBE ip_conntrack_irc |
-|# fi |
-| |
-| |
-|#Load the general IPTABLES NAT code - "iptable_nat" |
-|# - Loaded automatically when MASQ functionality is turned on |
-|# |
-|# - Loaded manually to clean up kernel auto-loading timing issues |
-|# |
-|echo -en "iptable_nat, " |
-|# |
-|#Verify the module isn't loaded. If it is, skip it |
-|# |
-|if [ -z "` $LSMOD | $GREP iptable_nat | $AWK {'print $1'} `" ]; then |
-| $MODPROBE iptable_nat |
-|fi |
-| |
-| |
-|#Loads the FTP NAT functionality into the core IPTABLES code |
-|# Required to support non-PASV FTP. |
-|# |
-|# Enabled by default -- insert a "#" on the next line to deactivate |
-|# |
-|echo -e "ip_nat_ftp" |
-|# |
-|#Verify the module isn't loaded. If it is, skip it |
-|# |
-|if [ -z "` $LSMOD | $GREP ip_nat_ftp | $AWK {'print $1'} `" ]; then |
-| $MODPROBE ip_nat_ftp |
-|fi |
-| |
-| |
-|#Loads the IRC NAT functionality (for DCC) into the core IPTABLES code |
-|# |
-|# DISABLED by default -- delete the "#" on the next few lines to activate |
-|# |
-|# echo -e "ip_nat_irc" |
-|# |
-|#Verify the module isn't loaded. If it is, skip it |
-|# |
-|# if [ -z "` $LSMOD | $GREP ip_nat_irc | $AWK {'print $1'} `" ]; then |
-|# $MODPROBE ip_nat_irc |
-|# fi |
-| |
-| |
-|echo " ---" |
-| |
-|# Just to be complete, here is a partial list of some of the other |
-|# IPTABLES kernel modules and their function. Please note that most |
-|# of these modules (the ipt ones) are automatically loaded by the |
-|# master kernel module for proper operation and don't need to be |
-|# manually loaded. |
-|# -------------------------------------------------------------------- |
-|# |
-|# ip_nat_snmp_basic - this module allows for proper NATing of some |
-|# SNMP traffic |
-|# |
-|# iptable_mangle - this target allows for packets to be |
-|# manipulated for things like the TCPMSS |
-|# option, etc. |
-|# |
-|# -- |
-|# |
-|# ipt_mark - this target marks a given packet for future action. |
-|# This automatically loads the ipt_MARK module |
-|# |
-|# ipt_tcpmss - this target allows to manipulate the TCP MSS |
-|# option for braindead remote firewalls. |
-|# This automatically loads the ipt_TCPMSS module |
-|# |
-|# ipt_limit - this target allows for packets to be limited to |
-|# to many hits per sec/min/hr |
-|# |
-|# ipt_multiport - this match allows for targets within a range |
-|# of port numbers vs. listing each port individually |
-|# |
-|# ipt_state - this match allows to catch packets with various |
-|# IP and TCP flags set/unset |
-|# |
-|# ipt_unclean - this match allows to catch packets that have invalid |
-|# IP/TCP flags set |
-|# |
-|# iptable_filter - this module allows for packets to be DROPped, |
-|# REJECTed, or LOGged. This module automatically |
-|# loads the following modules: |
-|# |
-|# ipt_LOG - this target allows for packets to be |
-|# logged |
-|# |
-|# ipt_REJECT - this target DROPs the packet and returns |
-|# a configurable ICMP packet back to the |
-|# sender. |
-| |
-| |
-|#CRITICAL: Enable IP forwarding since it is disabled by default since |
-|# |
-|# Redhat Users: you may try changing the options in |
-|# /etc/sysconfig/network from: |
-|# |
-|# FORWARD_IPV4=false |
-|# to |
-|# FORWARD_IPV4=true |
-|# |
-|echo " Enabling forwarding.." |
-|echo "1" > /proc/sys/net/ipv4/ip_forward |
-| |
-| |
-|# Dynamic IP users: |
-|# |
-|# If you get your IP address dynamically from SLIP, PPP, or DHCP, |
-|# enable the following option. This enables dynamic-address hacking |
-|# which makes the life with Diald and similar programs much easier. |
-|# |
-|echo " Enabling DynamicAddr.." |
-|echo "1" > /proc/sys/net/ipv4/ip_dynaddr |
-| |
-|echo " ---" |
-| |
-|############################################################################# |
-|# |
-|# Enable Stronger IP forwarding and Masquerading |
-|# |
-|# NOTE: In IPTABLES speak, IP Masquerading is a form of SourceNAT or SNAT. |
-|# |
-|# NOTE #2: The following is an example for an internal LAN address in the |
-|# 192.168.1.x network with a 255.255.255.0 or a "24" bit subnet |
-|# mask connecting to the Internet on external interface "eth0". |
-|# This example will MASQ internal traffic out to the Internet |
-|# but not allow non-initiated traffic into your internal network. |
-|# |
-|# |
-|# ** Please change the above network numbers, subnet mask, and your |
-|# *** Internet connection interface name to match your setup |
-|# |
-| |
-|#Clearing any previous configuration |
-|# |
-|# Unless specified, the defaults for INPUT, OUTPUT, and FORWARD to DROP |
-|# |
-|# You CANNOT change this to REJECT as it isn't a vaild policy setting. |
-|# If you want REJECT, you must explictly REJECT at the end of a giving |
-|# INPUT, OUTPUT, or FORWARD chain |
-|# |
-|echo " Clearing any existing rules and setting default policy to DROP.." |
-|$IPTABLES -P INPUT DROP |
-|$IPTABLES -F INPUT |
-|$IPTABLES -P OUTPUT DROP |
-|$IPTABLES -F OUTPUT |
-|$IPTABLES -P FORWARD DROP |
-|$IPTABLES -F FORWARD |
-|$IPTABLES -F -t nat |
-| |
-|#Not needed and it will only load the unneeded kernel module |
-|#$IPTABLES -F -t mangle |
-|# |
-|# Flush the user chain.. if it exists |
-|if [ -n "`$IPTABLES -L | $GREP drop-and-log-it`" ]; then |
-| $IPTABLES -F drop-and-log-it |
-|fi |
-|# |
-|# Delete all User-specified chains |
-|$IPTABLES -X |
-|# |
-|# Reset all IPTABLES counters |
-|$IPTABLES -Z |
-| |
-| |
-|#Configuring specific CHAINS for later use in the ruleset |
-|# |
-|# NOTE: Some users prefer to have their firewall silently |
-|# "DROP" packets while others prefer to use "REJECT" |
-|# to send ICMP error messages back to the remote |
-|# machine. The default is "REJECT" but feel free to |
-|# change this below. |
-|# |
-|# NOTE: Without the --log-level set to "info", every single |
-|# firewall hit will goto ALL vtys. This is a very big |
-|# pain. |
-|# |
-|echo " Creating a DROP chain.." |
-|$IPTABLES -N drop-and-log-it |
-|$IPTABLES -A drop-and-log-it -j LOG --log-level info |
-|$IPTABLES -A drop-and-log-it -j REJECT |
-| |
-|echo -e "\n - Loading INPUT rulesets" |
-| |
-| |
-|####################################################################### |
-|# INPUT: Incoming traffic from various interfaces. All rulesets are |
-|# already flushed and set to a default policy of DROP. |
-|# |
-| |
-|# loopback interfaces are valid. |
-|# |
-|$IPTABLES -A INPUT -i lo -s $UNIVERSE -d $UNIVERSE -j ACCEPT |
-| |
-| |
-|# local interface, local machines, going anywhere is valid |
-|# |
-|$IPTABLES -A INPUT -i $INTIF -s $INTNET -d $UNIVERSE -j ACCEPT |
-| |
-| |
-|# remote interface, claiming to be local machines, IP spoofing, get lost |
-|# |
-|$IPTABLES -A INPUT -i $EXTIF -s $INTNET -d $UNIVERSE -j drop-and-log-it |
-| |
-| |
-|# external interface, from any source, for ICMP traffic is valid |
-|# |
-|# If you would like your machine to "ping" from the Internet, |
-|# enable this next line |
-|# |
-|#$IPTABLES -A INPUT -i $EXTIF -p ICMP -s $UNIVERSE -d $EXTIP -j ACCEPT |
-| |
-| |
-|# remote interface, any source, going to permanent PPP address is valid |
-|# |
-|#$IPTABLES -A INPUT -i $EXTIF -s $UNIVERSE -d $EXTIP -j ACCEPT |
-| |
-| |
-|# Allow any related traffic coming back to the MASQ server in |
-|# |
-|$IPTABLES -A INPUT -i $EXTIF -s $UNIVERSE -d $EXTIP -m state --state \ |
-| ESTABLISHED,RELATED -j ACCEPT |
-| |
-| |
-|# ----- Begin OPTIONAL INPUT Section ----- |
-|# |
-| |
-|# DHCPd - Enable the following lines if you run an INTERNAL DHCPd server |
-|# |
-|#$IPTABLES -A INPUT -i $INTIF -p tcp --sport 68 --dport 67 -j ACCEPT |
-|#$IPTABLES -A INPUT -i $INTIF -p udp --sport 68 --dport 67 -j ACCEPT |
-| |
-|# HTTPd - Enable the following lines if you run an EXTERNAL WWW server |
-|# |
-|# NOTE: This is NOT needed for simply enabling PORTFW. This is ONLY |
-|# for users that plan on running Apache on the MASQ server itself |
-|# |
-|#echo -e " - Allowing EXTERNAL access to the WWW server" |
-|#$IPTABLES -A INPUT -i $EXTIF -m state --state NEW,ESTABLISHED,RELATED \ |
-|# -p tcp -s $UNIVERSE -d $EXTIP --dport 80 -j ACCEPT |
-| |
-|# |
-|# ----- End OPTIONAL INPUT Section ----- |
-| |
-| |
-| |
-|# Catch all rule, all other incoming is denied and logged. |
-|# |
-|$IPTABLES -A INPUT -s $UNIVERSE -d $UNIVERSE -j drop-and-log-it |
-| |
-| |
-|echo -e " - Loading OUTPUT rulesets" |
-| |
-|####################################################################### |
-|# OUTPUT: Outgoing traffic from various interfaces. All rulesets are |
-|# already flushed and set to a default policy of DROP. |
-|# |
-| |
-|# loopback interface is valid. |
-|# |
-|$IPTABLES -A OUTPUT -o lo -s $UNIVERSE -d $UNIVERSE -j ACCEPT |
-| |
-| |
-|# local interfaces, any source going to local net is valid |
-|# |
-|$IPTABLES -A OUTPUT -o $INTIF -s $EXTIP -d $INTNET -j ACCEPT |
-| |
-| |
-|# local interface, any source going to local net is valid |
-|# |
-|$IPTABLES -A OUTPUT -o $INTIF -s $INTIP -d $INTNET -j ACCEPT |
-| |
-| |
-|# outgoing to local net on remote interface, stuffed routing, deny |
-|# |
-|$IPTABLES -A OUTPUT -o $EXTIF -s $UNIVERSE -d $INTNET -j drop-and-log-it |
-| |
-| |
-|# anything else outgoing on remote interface is valid |
-|# |
-|$IPTABLES -A OUTPUT -o $EXTIF -s $EXTIP -d $UNIVERSE -j ACCEPT |
-| |
-| |
-|# ----- Begin OPTIONAL OUTPUT Section ----- |
-|# |
-| |
-|# DHCPd - Enable the following lines if you run an INTERNAL DHCPd server |
-|# - Remove BOTH #s all the #s if you need this functionality. |
-|# |
-|#$IPTABLES -A OUTPUT -o $INTIF -p tcp -s $INTIP --sport 67 \ |
-|# -d 255.255.255.255 --dport 68 -j ACCEPT |
-|#$IPTABLES -A OUTPUT -o $INTIF -p udp -s $INTIP --sport 67 \ |
-|# -d 255.255.255.255 --dport 68 -j ACCEPT |
-| |
-|# |
-|# ----- End OPTIONAL OUTPUT Section ----- |
-| |
-| |
-|# Catch all rule, all other outgoing is denied and logged. |
-|# |
-|$IPTABLES -A OUTPUT -s $UNIVERSE -d $UNIVERSE -j drop-and-log-it |
-| |
-| |
-|echo -e " - Loading FORWARD rulesets" |
-| |
-|####################################################################### |
-|# FORWARD: Enable Forwarding and thus IPMASQ |
-|# |
-| |
-|# ----- Begin OPTIONAL FORWARD Section ----- |
-|# |
-|# ----- End OPTIONAL FORWARD Section ----- |
-| |
-| |
-|echo " - FWD: Allow all connections OUT and only existing/related IN" |
-|$IPTABLES -A FORWARD -i $EXTIF -o $INTIF -m state --state ESTABLISHED,RELATED \ |
-| -j ACCEPT |
-|$IPTABLES -A FORWARD -i $INTIF -o $EXTIF -j ACCEPT |
-| |
-|# Catch all rule, all other forwarding is denied and logged. |
-|# |
-|$IPTABLES -A FORWARD -j drop-and-log-it |
-| |
-| |
-|echo " - NAT: Enabling SNAT (MASQUERADE) functionality on $EXTIF" |
-|# |
-|#More liberal form |
-|#$IPTABLES -t nat -A POSTROUTING -o $EXTIF -j MASQUERADE |
-|# |
-|#Stricter form |
-|$IPTABLES -t nat -A POSTROUTING -o $EXTIF -j SNAT --to $EXTIP |
-| |
-| |
-|####################################################################### |
-|echo -e "\nStronger rc.firewall-2.4 $FWVER done.\n" |
-+---------------------------------------------------------------------------------+
-
-
-To automatically start this stronger firewall ruleset at the proper time,
-please see the end of the Section 3.4.2 section for full details. Please make
-sure you make the correct "rc.firewall-2.4" to "rc.firewall-2.4-stronger"
-substitutions!!
------------------------------------------------------------------------------
-
-6.4.2. Stronger IP Firewall (IPCHAINS) rulesets
-
-This section provides a more in-depth guide to using the 2.2.x firewall tool,
-IPCHAINS. See above sections for IPFWADM rulesets.
-
-This example is for a firewall/masquerade system behind a PPP link with a
-static PPP address (dynamic PPP instructions are included but disabled). The
-trusted interface is 192.168.0.1 and the PPP interface IP address has been
-changed to protect the guilty :-). I have listed each incoming and outgoing
-interface individually to catch IP spoofing as well as stuffed routing and/or
-masquerading. A nything not explicitly allowed is FORBIDDEN (well.. rejected
-actually). If your IP MASQ box breaks after implementing this rc.firewall
-script, be sure that you edit it for your configuration and check your /var/
-log/messages or /var/adm/messages SYSLOG file for any firewall errors.
-
-For more comprehensive examples of a strong IP Masqueraded IPFWADM rulesets
-for PPP, Cablemodem users, etc., please see [http://www.ecst.csuchico.edu/
-~dranch/LINUX/index-linux.html#TrinityOS] TrinityOS - Section 10 and [http://
-www.greatcircle.com/] GreatCircle's Firewall WWW page
-
-NOTE #1: --- UPDATE YOUR KERNEL --- Linux 2.2.x kernels less than version
-2.2.20 contain several different security vulnerabilities (some were MASQ
-specific). Kernels less than 2.2.20 have a few local vulnerabilities. Kernel
-versions less than 2.2.16 have a TCP root exploit vulnerability and versions
-less than 2.2.11 have a IPCHAINS fragmentation bug. Because of these issues,
-users running a firewall with strong IPCHAINS rulesets are open to possible
-instrusion. Please upgrade your kernel to a fixed version.
-
-NOTE #2: If you get a dynamically assigned TCP/IP address from your ISP (PPP,
-ADSL, Cablemodems, etc.), you CANNOT load this strong ruleset upon booting.
-You will either need to reload this firewall ruleset EVERY TIME you get a new
-IP address or make your /etc/rc.d/rc.firewall ruleset more intelligent. To do
-this for PPP users, carefully read and un-comment out the proper lines in the
-"Dynamic PPP IP fetch" section below. You can also find more details in the
-[http://www.ecst.csuchico.edu/~dranch/LINUX/index-linux.html#TrinityOS]
-TrinityOS - Section 10 doc for more details on Strong rulesets and Dynamic IP
-addresses.
-
-Please also be aware that there are several GUI Firewall creation tools
-available as well. Please see Chapter 7for full details.
-
-Lastly, if you are using a STATIC PPP IP address, change the "EXTIF=
-"your.static.PPP.address"" line to reflect your address.
-
-----------------------------------------------------------------
-
-
-+-----------------------------------------------------------------------------------+
-|#!/bin/sh |
-|# |
-|# /etc/rc.d/rc.firewall: An example of a Stronger IPCHAINS firewall |
-|# ruleset for 2.2 kernels |
-|# |
-|FWVER=0.71s |
-|# |
-|# Log: |
-|# 0.71s - ruleset now uses modprobe instead of insmod |
-|# 0.70s - Added missing execution variables |
-|# - fixed a missing -p tcp for the commented HTTPd section |
-|# 0.65s - Added comments HTTPd rules to the INPUT and OUTPUT section |
-|# - Added a comment where to insert IPPORTFW commands |
-|# 0.60s - Changed the EXTIP command to work on NON-English distros |
-|# - Updated the CASE of some of the script variables |
-|# |
-| |
-|echo -e "\nLoading rc.firewall-2.2-stronger : version $FWVER..\n" |
-| |
-| |
-|# The location of various iptables and other shell programs |
-|# |
-|# If your Linux distribution came with a copy of iptables, most |
-|# likely it is located in /sbin. If you manually compiled |
-|# iptables, the default location is in /usr/local/sbin |
-|# |
-|# ** Please use the "whereis iptables" command to figure out |
-|# ** where your copy is and change the path below to reflect |
-|# ** your setup |
-|# |
-|IPCHAINS=/sbin/ipchains |
-|LSMOD=/sbin/lsmod |
-|DEPMOD=/sbin/depmod |
-|MODPROBE=/sbin/modprobe |
-|GREP=/bin/grep |
-|AWK=/bin/awk |
-|SED=/bin/sed |
-|IFCONFIG=/sbin/ifconfig |
-| |
-|PATH=/sbin:/bin:/usr/sbin:/usr/bin |
-| |
-| |
-|# Global variables |
-|# ---------------- |
-| |
-|# ALL PPP and DHCP users must set this for the correct EXTERNAL and |
-|# INTERNAL interfaces names. Examples: eth0, ppp0, ippp0, etc. |
-|# |
-|EXTIF="ppp0" |
-|INTIF="eth0" |
-| |
-|# The INTERNAL IP address |
-|# |
-|INTNET="192.168.0.0/24" |
-| |
-| |
-| |
-|# Load all required IP MASQ modules |
-|# |
-|# NOTE: Only load the IP MASQ modules you need. All current IP MASQ modules |
-|# are shown below but are commented from loading. |
-| |
-|# Needed to initially load modules |
-|# |
-|$DEPMOD -a |
-| |
-|# Supports the proper masquerading of FTP file transfers using the PORT method |
-|# |
-|$MODPROBE ip_masq_ftp |
-| |
-|# Supports the masquerading of RealAudio over UDP. Without this module, |
-|# RealAudio WILL function but in TCP mode. This can cause a reduction |
-|# in sound quality |
-|# |
-|$MODPROBE ip_masq_raudio |
-| |
-|# Supports the masquerading of IRC DCC file transfers |
-|# |
-|#$MODPROBE ip_masq_irc |
-| |
-| |
-|# Supports the masquerading of Quake and QuakeWorld by default. These modules are |
-|# for multiple users behind the Linux MASQ server. If you are going to |
-|# play Quake I, II, and III, use the second example. |
-|# |
-|# NOTE: If you get ERRORs loading the QUAKE module, you are running an old |
-|# ----- kernel that has bugs in it. Please upgrade to the newest kernel. |
-|# |
-|#Quake I / QuakeWorld (ports 26000 and 27000) |
-|#$MODPROBE ip_masq_quake |
-|# |
-|#Quake I/II/III / QuakeWorld (ports 26000, 27000, 27910, 27960) |
-|#$MODPROBE ip_masq_quake 26000,27000,27910,27960 |
-| |
-| |
-|# Supports the masquerading of the CuSeeme video conferencing software |
-|# |
-|#$MODPROBE ip_masq_cuseeme |
-| |
-|#Supports the masquerading of the VDO-live video conferencing software |
-|# |
-|#$MODPROBE ip_masq_vdolive |
-| |
-| |
-|#CRITICAL: Enable IP forwarding since it is disabled by default |
-|# |
-|# Redhat Users: you may try changing the options in |
-|# /etc/sysconfig/network from: |
-|# |
-|# FORWARD_IPV4=false |
-|# to |
-|# FORWARD_IPV4=true |
-|# |
-|echo "1" > /proc/sys/net/ipv4/ip_forward |
-| |
-| |
-|#CRITICAL: Enable automatic IP defragmentation since it is disabled by default |
-|# in 2.2.x kernels |
-|# |
-|# This used as a compile-time option but the behavior was changed |
-|# in 2.2.12. It should also be noted that some distributions have |
-|# removed this option from the /proc table. If this entry isn't |
-|# present in your /proc, don't worry about it. |
-|# |
-|echo "1" > /proc/sys/net/ipv4/ip_always_defrag |
-| |
-| |
-|# Dynamic IP users: |
-|# |
-|# If you get your IP address dynamically from SLIP, PPP, or DHCP, enable this |
-|# following option. This enables dynamic-ip address hacking in IP MASQ, |
-|# making life with Diald and similar programs much easier. |
-|# |
-|#echo "1" > /proc/sys/net/ipv4/ip_dynaddr |
-| |
-| |
-|# Enable the LooseUDP patch which some Internet-based games require |
-|# |
-|# If you are trying to get an Internet game to work through your IP MASQ box, |
-|# and you configured it to the best of your ability without it working, try |
-|# enabling this option (delete the "#" character). This option is disabled |
-|# by default due to possible internal machine UDP port scanning |
-|# vulnerabilities. |
-|# |
-|#echo "1" > /proc/sys/net/ipv4/ip_masq_udp_dloose |
-| |
-| |
-|# Specify your Static IP address here. |
-|# |
-|# If you have a DYNAMIC IP address, you need to make this ruleset recognize |
-|# your IP address everytime you get a new IP. To do this, enable the |
-|# following one-line script. (Please note that the different single and |
-|# double quote characters MATTER). |
-|# |
-|# |
-|# DHCP users: |
-|# ----------- |
-|# If you get your TCP/IP address via DHCP, **you will need ** to enable the |
-|# #ed out command below underneath the PPP section AND replace the word |
-|# "ppp0" with the name of your EXTERNAL Internet connection (eth0, eth1, etc) |
-|# on the lines for "ppp-ip" and "EXTIP". You should note that the |
-|# DHCP server can change IP addresses on you. To fix this, users should |
-|# configure their DHCP client to re-run the firewall ruleset everytime the |
-|# DHCP lease is renewed. |
-|# |
-|# NOTE #1: Some DHCP clients like the original "pump" (the newer |
-|# versions have been fixed) did NOT have the ability to run |
-|# scripts after a lease-renew. Because of this, you need to |
-|# replace it with something like "dhcpcd" or "dhclient". |
-|# |
-|# NOTE #2: The syntax for "dhcpcd" has changed in recent versions. |
-|# |
-|# Older versions used syntax like: |
-|# dhcpcd -c /etc/rc.d/rc.firewall eth0 |
-|# |
-|# Newer versions use syntax like: |
-|# dhcpcd eth0 /etc/rc.d/rc.firewall |
-|# |
-|# NOTE #3: For Pump users, put the following line in /etc/pump.conf: |
-|# |
-|# script /etc/rc.d/rc.firewall |
-|# |
-|# PPP users: |
-|# ---------- |
-|# If you aren't already aware, the /etc/ppp/ip-up script is always run when |
-|# a PPP connection comes up. Because of this, we can make the ruleset go and |
-|# get the new PPP IP address and update the strong firewall ruleset. |
-|# |
-|# If the /etc/ppp/ip-up file already exists, you should edit it and add a line |
-|# containing "/etc/rc.d/rc.firewall" near the end of the file. |
-|# |
-|# If you don't already have a /etc/ppp/ip-up sccript, you need to create the |
-|# following link to run the /etc/rc.d/rc.firewall script. |
-|# |
-|# ln -s /etc/rc.d/rc.firewall /etc/ppp/ip-up |
-|# |
-|# * You then want to enable the #ed out shell command below * |
-|# |
-|# |
-|# Determine the external IP automatically: |
-|# ---------------------------------------- |
-|# |
-|# The following line will determine your external IP address. This |
-|# line is somewhat complex and confusing but it will also work for |
-|# all NON-English Linux distributions. |
-|# |
-|# Make sure the EXTIF variable above is set to reflect the name |
-|# of your Internet connection |
-|# |
-|EXTIP="`$IFCONFIG $EXTIF | $AWK \ |
-| /$EXTIF/'{next}//{split($0,a,":");split(a[2],a," ");print a[1];exit}'`" |
-| |
-| |
-| |
-|# MASQ timeouts |
-|# |
-|# 2 hrs timeout for TCP session timeouts |
-|# 10 sec timeout for traffic after the TCP/IP "FIN" packet is received |
-|# 60 sec timeout for UDP traffic (MASQ'ed ICQ users must enable a 30sec |
-|# firewall timeout in ICQ itself) |
-|# |
-|$IPCHAINS -M -S 7200 10 60 |
-| |
-|############################################################################# |
-|# Incoming, flush and set default policy of reject. Actually the default policy |
-|# is irrelevant because there is a catch all rule with deny and log. |
-|# |
-|$IPCHAINS -F input |
-|$IPCHAINS -P input REJECT |
-| |
-|# local interface, local machines, going anywhere is valid |
-|# |
-|$IPCHAINS -A input -i $INTIF -s $INTNET -d 0.0.0.0/0 -j ACCEPT |
-| |
-|# remote interface, claiming to be local machines, IP spoofing, get lost |
-|# |
-|$IPCHAINS -A input -i $EXTIF -s $INTNET -d 0.0.0.0/0 -l -j REJECT |
-| |
-|# remote interface, any source, going to permanent PPP address is valid |
-|# |
-|$IPCHAINS -A input -i $EXTIF -s 0.0.0.0/0 -d $EXTIP/32 -j ACCEPT |
-| |
-|# loopback interface is valid. |
-|# |
-|$IPCHAINS -A input -i lo -s 0.0.0.0/0 -d 0.0.0.0/0 -j ACCEPT |
-| |
-| |
-|# ----- Begin OPTIONAL INPUT Section ----- |
-|# |
-| |
-|# HTTPd - Enable the following lines if you either run a WWW server on |
-|# the IPMASQ server -OR- plan on PORTFW'ing HTTP traffic to |
-|# an internal WWW server |
-|# |
-|#$IPCHAINS -A input -i $EXTIF -p tcp -s 0.0.0.0/0 -d $EXTIP 80 -j ACCEPT |
-| |
-|# |
-|# ----- End OPTIONAL INPUT Section ----- |
-| |
-| |
-|# catch all rule, all other incoming is denied and logged. pity there is no |
-|# log option on the policy but this does the job instead. |
-|# |
-|$IPCHAINS -A input -s 0.0.0.0/0 -d 0.0.0.0/0 -l -j REJECT |
-| |
-|############################################################################# |
-|# Outgoing, flush and set default policy of reject. Actually the default policy |
-|# is irrelevant because there is a catch all rule with deny and log. |
-|# |
-|$IPCHAINS -F output |
-|$IPCHAINS -P output REJECT |
-| |
-|# local interface, any source going to local net is valid |
-|# |
-|$IPCHAINS -A output -i $INTIF -s 0.0.0.0/0 -d $INTNET -j ACCEPT |
-| |
-|# outgoing to local net on remote interface, stuffed routing, deny |
-|# |
-|$IPCHAINS -A output -i $EXTIF -s 0.0.0.0/0 -d $INTNET -l -j REJECT |
-| |
-|# outgoing from local net on remote interface, stuffed masquerading, deny |
-|# |
-|$IPCHAINS -A output -i $EXTIF -s $INTNET -d 0.0.0.0/0 -l -j REJECT |
-| |
-|# anything else outgoing on remote interface is valid |
-|# |
-|$IPCHAINS -A output -i $EXTIF -s $EXTIP/32 -d 0.0.0.0/0 -j ACCEPT |
-| |
-|# loopback interface is valid. |
-|# |
-|$IPCHAINS -A output -i lo -s 0.0.0.0/0 -d 0.0.0.0/0 -j ACCEPT |
-| |
-| |
-|# ----- Begin OPTIONAL OUTPUT Section ----- |
-|# |
-| |
-|# HTTPd - Enable the following lines if you either run a WWW server on |
-|# the IPMASQ server -OR- plan on PORTFW'ing HTTP traffic to |
-|# an internal WWW server |
-|# |
-|#$IPCHAINS -A output -i $EXTIF -p tcp -s $EXTIP 80 -d 0.0.0.0/0 -j ACCEPT |
-| |
-|# |
-|# ----- End OPTIONAL OUTPUT Section ----- |
-| |
-|# catch all rule, all other outgoing is denied and logged. pity there is no |
-|# log option on the policy but this does the job instead. |
-|# |
-|$IPCHAINS -A output -s 0.0.0.0/0 -d 0.0.0.0/0 -l -j REJECT |
-| |
-|############################################################################# |
-|# Forwarding, flush and set default policy of deny. Actually the default policy |
-|# is irrelevant because there is a catch all rule with deny and log. |
-|# |
-|$IPCHAINS -F forward |
-|$IPCHAINS -P forward DENY |
-| |
-| |
-|# ----- Begin OPTIONAL FORWARD Section ----- |
-|# |
-|# ----- End OPTIONAL FORWARD Section ----- |
-| |
-| |
-|# Masquerade from local net on local interface to anywhere. |
-|# |
-|$IPCHAINS -A forward -i $EXTIF -s $INTNET -d 0.0.0.0/0 -j MASQ |
-|# |
-|# catch all rule, all other forwarding is denied and logged. pity there is no |
-|# log option on the policy but this does the job instead. |
-|# |
-|$IPCHAINS -A forward -s 0.0.0.0/0 -d 0.0.0.0/0 -l -j REJECT |
-| |
-|#End of file. |
-+-----------------------------------------------------------------------------------+
-
-
-To automatically start this stronger firewall ruleset at the proper time,
-please see the end of the Section 3.4.2 section for full details. Please make
-sure you make the correct "rc.firewall-2.2" to "rc.firewall-2.2-stronger"
-substitutions!!
-
-With IPCHAINS, you can block traffic to a particular site using the "input",
-"output", and/or "forward" rules. Remember that the set of rules are scanned
-from top to bottom and "-A" tells IPCHIANS to "append" this new rule to the
-existing set of rules. So with this in mind, any specific restrictions need
-to come before any global rules. For example:
-
-Using "input" rules:
-
-Probably the fastest and most efficient method to block traffic, but this
-method only stops the MASQed machines and NOT the firewall machine itself. Of
-course, you might want to allow that combination.
-
-Anyway, to block 204.50.10.13:
-
-+---------------------------------------------------------------------------+
-|In the /etc/rc.d/rc.firewall ruleset: |
-|... start of "input" rules ... |
-| |
-|# reject and log local interface, local machines going to 204.50.10.13 |
-|# |
-|ipchains -A input -s 192.168.0.0/24 -d 204.50.10.13/32 -l -j REJECT |
-| |
-| |
-|# local interface, local machines, going anywhere is valid |
-|# |
-|ipchains -A input -s 192.168.0.0/24 -d 0.0.0.0/0 -l -j ACCEPT |
-| |
-| |
-|... end of "input" rules ... |
-+---------------------------------------------------------------------------+
-
-Using "output" rules:
-
-This is the slower method to block traffic because the packets must go
-through masquerading before they are dropped. Yet, this rule even stops the
-firewall machine from accessing the forbidden site.
-
-... start of "output" rules ... # reject and log outgoing to 204.50.10.13 #
-ipchains -A output -s $ppp_ip/32 -d 204.50.10.13/32 -l -j REJECT # anything
-else outgoing on remote interface is valid # ipchains -A output -s $ppp_ip/32
--d 0.0.0.0/0 -l -j ACCEPT ... end of "output" rules ...
-
-Using "forward" rules:
-
-Probably slower than "input" rules for blocking traffic, this only stops
-masqueraded machines (e.g. internal machines). The firewall machine can still
-reach forbidden site(s).
-
-... start of "forward" rules ... # Reject and log from local net on PPP
-interface to 204.50.10.13. # ipchains -A forward -i ppp0 -s 192.168.0.0/24 -d
-204.50.10.13/32 -l -j REJECT # Masquerade from local net on local interface
-to anywhere. # ipchains -A forward -i ppp0 -s 192.168.0.0/24 -d 0.0.0.0/0 -j
-MASQ ... end of "forward" rules ...
-
-No need for a special rule to allow machines on the 192.168.0.0/24 network to
-go to 204.50.11.0. Why? It is already covered by the global MASQ rule.
-
-NOTE: Unlike IPFWADM, IPCHIANS has only one way of coding the interfaces
-name. IPCHAINS uses the "-i eth0" option where as IPFWADM had both "-W" for
-the interface name and "-V" for the interface's IP address.
------------------------------------------------------------------------------
-
-6.4.3. Stronger IP Firewall (IPFWADM) Rulesets
-
-This section provides a more in-depth guide on using the 2.0.x firewall tool,
-IPFWADM. See below for IPCHAINS rulesets
-
-This example is for a firewall/masquerade system behind a PPP link with a
-static PPP address (dynamic PPP instructions are included but disabled). The
-trusted interface is 192.168.0.1 and the PPP interface IP address has been
-changed to protect the guilty :). I have listed each incoming and outgoing
-interface individually to catch IP spoofing as well as stuffed routing and/or
-masquerading. Anything not explicitly allowed is FORBIDDEN (well.. rejected,
-actually). If your IP MASQ box breaks after implementing this rc.firewall
-script, be sure that you edit it for your configuration and check your /var/
-log/messages or /var/adm/messages SYSLOG file for any firewall errors.
-
-For more comprehensive examples of a strong IP Masqueraded IPFWADM rulesets
-for PPP, Cablemodem users, etc., please see [http://www.ecst.csuchico.edu/
-~dranch/LINUX/index-linux.html#TrinityOS] TrinityOS - Section 10 and [http://
-www.greatcircle.com/] GreatCircle's Firewall WWW page
-
-NOTE: If you get a dynamically assigned TCP/IP address from your ISP (PPP,
-ADSL, Cablemodems, etc.), you CANNOT load this strong ruleset upon boot. You
-will either need to reload this firewall ruleset EVERY TIME you get a new IP
-address or make your /etc/rc.d/rc.firewall ruleset more intelligent. To do
-this for PPP users, carefully read and un-comment out the proper lines in the
-"Dynamic PPP IP fetch" section below. You can also find more details on
-Strong rulesets and Dynamic IP addresses in the [http://www.ecst.csuchico.edu
-/~dranch/LINUX/index-linux.html#TrinityOS] TrinityOS - Section 10 docs.
-
-Please also be aware that there are several GUI Firewall creation tools
-available as well. Please see Chapter 7for full details.
-
-Lastly, if you are using a STATIC PPP IP address, change the "ppp_ip=
-"your.static.PPP.address"" line to reflect your address.
-
-----------------------------------------------------------------
-
-
-+-----------------------------------------------------------------------------------------+
-|#!/bin/sh |
-|# |
-|# /etc/rc.d/rc.firewall: An example of a semi-STRONG IPFWADM firewall ruleset |
-|# |
-| |
-|PATH=/sbin:/bin:/usr/sbin:/usr/bin |
-| |
-|# testing, wait a bit then clear all firewall rules. |
-|# uncomment the following lines if you want the firewall to automatically |
-|# disable after 10 minutes. |
-|# |
-|# Disabled by default |
-|# |
-|# (sleep 600; \ |
-|# ipfwadm -I -f; \ |
-|# ipfwadm -I -p accept; \ |
-|# ipfwadm -O -f; \ |
-|# ipfwadm -O -p accept; \ |
-|# ipfwadm -F -f; \ |
-|# ipfwadm -F -p accept; \ |
-|# ) & |
-| |
-| |
-|# Load all required IP MASQ modules |
-|# |
-|# NOTE: Only load the IP MASQ modules you need. All current IP MASQ modules |
-|# are shown below but are commented from loading. |
-| |
-|# Needed to initially load modules |
-|# |
-|/sbin/depmod -a |
-| |
-|# Supports the proper masquerading of FTP file transfers using the PORT method |
-|# |
-|/sbin/modprobe ip_masq_ftp |
-| |
-|# Supports the masquerading of RealAudio over UDP. Without this module, |
-|# RealAudio WILL function but in TCP mode. This can cause a reduction |
-|# in sound quality |
-|# |
-|#/sbin/modprobe ip_masq_raudio |
-| |
-|# Supports the masquerading of IRC DCC file transfers |
-|# |
-|#/sbin/modprobe ip_masq_irc |
-| |
-| |
-|# Supports the masquerading of Quake and QuakeWorld by default. This modules is |
-|# for multiple users behind the Linux MASQ server. If you are going to |
-|# play Quake I, II, and III, use the second example. |
-|# |
-|# NOTE: If you get ERRORs loading the QUAKE module, you are running an old |
-|# ----- kernel that has bugs in it. Please upgrade to the newest kernel. |
-|# |
-|#Quake I / QuakeWorld (ports 26000 and 27000) |
-|#/sbin/modprobe ip_masq_quake |
-|# |
-|#Quake I/II/III / QuakeWorld (ports 26000, 27000, 27910, 27960) |
-|#/sbin/modprobe ip_masq_quake 26000,27000,27910,27960 |
-| |
-| |
-|# Supports the masquerading of the CuSeeme video conferencing software |
-|# |
-|#/sbin/modprobe ip_masq_cuseeme |
-| |
-|#Supports the masquerading of the VDO-live video conferencing software |
-|# |
-|#/sbin/modprobe ip_masq_vdolive |
-| |
-| |
-|#CRITICAL: Enable IP forwarding, since it is disabled by default |
-|# |
-|# Redhat Users: you may try changing the options in /etc/sysconfig/network |
-|# from: |
-|# |
-|# FORWARD_IPV4=false |
-|# to |
-|# FORWARD_IPV4=true |
-|# |
-|echo "1" > /proc/sys/net/ipv4/ip_forward |
-| |
-| |
-|#CRITICAL: Enable automatic IP defragmenting since it is disabled by default |
-|# in 2.2.x kernels |
-|# |
-|# This used to be a compile-time option but the behavior was changed |
-|# in 2.2.12 |
-|# |
-|echo "1" > /proc/sys/net/ipv4/ip_always_defrag |
-| |
-| |
-|# Dynamic IP users: |
-|# |
-|# If you get your IP address dynamically from SLIP, PPP, or DHCP, enable this |
-|# following option. This allows dynamic-ip address hacking in IP MASQ, |
-|# making the life with Diald and similar programs much easier. |
-|# |
-|#echo "1" > /proc/sys/net/ipv4/ip_dynaddr |
-| |
-| |
-|# Specify your Static IP address here. |
-|# |
-|# If you have a DYNAMIC IP address, you need to make this ruleset understand |
-|# your IP address everytime you get a new IP. To do this, enable the |
-|# following one-line script. (Please note that the different single and |
-|# double quote characters MATTER). |
-|# |
-|# |
-|# DHCP users: |
-|# ----------- |
-|# If you get your TCP/IP address via DHCP, **you will need ** to enable the |
-|# #ed out command below underneath the PPP section AND replace the word |
-|# "ppp0" with the name of your EXTERNAL Internet connection (eth0, eth1, |
-|# etc). It should be also noted that the DHCP server can change IP |
-|# addresses on you. To fix this, users should configure their DHCP client |
-|# to re-run the firewall ruleset everytime the DHCP lease is renewed. |
-|# |
-|# NOTE #1: Some DHCP clients like the older version of "pump" (the newer |
-|# versions have been fixed) did NOT have the ability to run |
-|# scripts after a lease-renew. Because of this, you need to |
-|# replace it with something like "dhcpcd" or "dhclient". |
-|# |
-|# NOTE #2: The syntax for "dhcpcd" has changed in recent versions. |
-|# |
-|# Older versions used syntax like: |
-|# dhcpcd -c /etc/rc.d/rc.firewall eth0 |
-|# |
-|# Newer versions use syntax like: |
-|# dhcpcd eth0 /etc/rc.d/rc.firewall |
-|# |
-|# NOTE #3: For Pump users, put the following line in /etc/pump.conf: |
-|# |
-|# script /etc/rc.d/rc.firewall |
-|# |
-|# PPP users: |
-|# ---------- |
-|# If you aren't already aware, the /etc/ppp/ip-up script is always run when |
-|# a PPP connection comes up. Because of this, we can make the ruleset go |
-|# and get the new PPP IP address and update the strong firewall ruleset. |
-|# |
-|# If the /etc/ppp/ip-up file already exists, you should edit it and add a line |
-|# containing "/etc/rc.d/rc.firewall" near the end of the file. |
-|# |
-|# If you don't already have a /etc/ppp/ip-up sccript, you need to create the |
-|# following link to run the /etc/rc.d/rc.firewall script. |
-|# |
-|# ln -s /etc/rc.d/rc.firewall /etc/ppp/ip-up |
-|# |
-|# * You then want to enable the #ed out shell command below * |
-|# |
-|# |
-|# PPP and DHCP Users: |
-|# ------------------- |
-|# Remove the # on the line below and place a # in front of the line after that. |
-|# |
-|#ppp_ip="`/sbin/ifconfig ppp0 | grep 'inet addr' | awk '{print $2}' | sed -e 's/.*://'`" |
-|# |
-|ppp_ip="your.static.PPP.address" |
-| |
-| |
-|# MASQ timeouts |
-|# |
-|# 2 hrs timeout for TCP session timeouts |
-|# 10 sec timeout for traffic after the TCP/IP "FIN" packet is received |
-|# 60 sec timeout for UDP traffic (MASQ'ed ICQ users must enable a 30sec |
-|# firewall timeout in ICQ itself) |
-|# |
-|/sbin/ipfwadm -M -s 7200 10 60 |
-| |
-| |
-|############################################################################# |
-|# Incoming, flush and set default policy of reject. Actually the default policy |
-|# is irrelevant because there is a catch all rule with deny and log. |
-|# |
-|/sbin/ipfwadm -I -f |
-|/sbin/ipfwadm -I -p reject |
-| |
-|# local interface, local machines, going anywhere is valid |
-|# |
-|/sbin/ipfwadm -I -a accept -V 192.168.0.1 -S 192.168.0.0/24 -D 0.0.0.0/0 |
-| |
-|# remote interface, claiming to be local machines, IP spoofing, get lost |
-|# |
-|/sbin/ipfwadm -I -a reject -V $ppp_ip -S 192.168.0.0/24 -D 0.0.0.0/0 -o |
-| |
-|# remote interface, any source, going to permanent PPP address is valid |
-|# |
-|/sbin/ipfwadm -I -a accept -V $ppp_ip -S 0.0.0.0/0 -D $ppp_ip/32 |
-| |
-|# loopback interface is valid. |
-|# |
-|/sbin/ipfwadm -I -a accept -V 127.0.0.1 -S 0.0.0.0/0 -D 0.0.0.0/0 |
-| |
-|# catch all rule, all other incoming is denied and logged. pity there is no |
-|# log option on the policy but this does the job instead. |
-|# |
-|/sbin/ipfwadm -I -a reject -S 0.0.0.0/0 -D 0.0.0.0/0 -o |
-| |
-| |
-|############################################################################# |
-|# Outgoing, flush and set default policy of reject. Actually the default policy |
-|# is irrelevant because there is a catch all rule with deny and log. |
-|# |
-|/sbin/ipfwadm -O -f |
-|/sbin/ipfwadm -O -p reject |
-| |
-|# local interface, any source going to local net is valid |
-|# |
-|/sbin/ipfwadm -O -a accept -V 192.168.0.1 -S 0.0.0.0/0 -D 192.168.0.0/24 |
-| |
-|# outgoing to local net on remote interface, stuffed routing, deny |
-|# |
-|/sbin/ipfwadm -O -a reject -V $ppp_ip -S 0.0.0.0/0 -D 192.168.0.0/24 -o |
-| |
-|# outgoing from local net on remote interface, stuffed masquerading, deny |
-|# |
-|/sbin/ipfwadm -O -a reject -V $ppp_ip -S 192.168.0.0/24 -D 0.0.0.0/0 -o |
-| |
-|# outgoing from local net on remote interface, stuffed masquerading, deny |
-|# |
-|/sbin/ipfwadm -O -a reject -V $ppp_ip -S 0.0.0.0/0 -D 192.168.0.0/24 -o |
-| |
-|# anything else outgoing on remote interface is valid |
-|# |
-|/sbin/ipfwadm -O -a accept -V $ppp_ip -S $ppp_ip/32 -D 0.0.0.0/0 |
-| |
-|# loopback interface is valid. |
-|# |
-|/sbin/ipfwadm -O -a accept -V 127.0.0.1 -S 0.0.0.0/0 -D 0.0.0.0/0 |
-| |
-|# catch all rule, all other outgoing is denied and logged. pity there is no |
-|# log option on the policy but this does the job instead. |
-|# |
-|/sbin/ipfwadm -O -a reject -S 0.0.0.0/0 -D 0.0.0.0/0 -o |
-| |
-| |
-|############################################################################# |
-|# Forwarding, flush and set default policy of deny. Actually the default policy |
-|# is irrelevant because there is a catch all rule with deny and log. |
-|# |
-|/sbin/ipfwadm -F -f |
-|/sbin/ipfwadm -F -p reject |
-| |
-|# Masquerade from local net on local interface to anywhere. |
-|# |
-|/sbin/ipfwadm -F -a masquerade -W ppp0 -S 192.168.0.0/24 -D 0.0.0.0/0 |
-|# |
-|# catch all rule, all other forwarding is denied and logged. Pity there is no |
-|# log option on the policy but this does the job instead. |
-|# |
-|/sbin/ipfwadm -F -a reject -S 0.0.0.0/0 -D 0.0.0.0/0 -o |
-| |
-|#End of file. |
-+-----------------------------------------------------------------------------------------+
-
-
-To automatically start this stronger firewall ruleset at the proper time,
-please see the end of the Section 3.4.3 section for full details. Please make
-sure you make the correct "rc.firewall-2.0" to "rc.firewall-2.0-stronger"
-substitutions!!
-
-With IPFWADM, you can block traffic to a particular site using the -I, -O or
--F rules. Remember that the set of rules are scanned top to bottom and "-a"
-tells IPFWADM to "append" this new rule to the existing set of rules. So with
-this in mind, any specific restrictions need to come before global rules. For
-example:
-
-Using -I (input ) rules:
-
-Probably the fastest and most efficient method to block traffic but it only
-stops the MASQed machines, and NOT the the firewall machine itself. Of
-course, you might want to allow that combination.
-
-Anyway, to block 204.50.10.13:
-
-In the /etc/rc.d/rc.firewall ruleset: ... start of -I rules ... # reject and
-log local interface, local machines going to 204.50.10.13 # /sbin/ipfwadm -I
--a reject -V 192.168.0.1 -S 192.168.0.0/24 -D 204.50.10.13/32 -o # local
-interface, local machines, going anywhere is valid # /sbin/ipfwadm -I -a
-accept -V 192.168.0.1 -S 192.168.0.0/24 -D 0.0.0.0/0 ... end of -I rules ...
-
-Using -O (output) rules:
-
-This is the slower method to block traffic because the packets go through
-masquerading first before they are dropped. Yet, this rule even stops the
-firewall machine from accessing the forbidden site.
-
-... start of -O rules ... # reject and log outgoing to 204.50.10.13 # /sbin/
-ipfwadm -O -a reject -V $ppp_ip -S $ppp_ip/32 -D 204.50.10.13/32 -o #
-anything else outgoing on remote interface is valid # /sbin/ipfwadm -O -a
-accept -V $ppp_ip -S $ppp_ip/32 -D 0.0.0.0/0 ... end of -O rules ...
-
-Using -F (forward) rules:
-
-Probably slower than -I (input) rules for blocking traffic, this still only
-stops masqueraded machines (e.g. internal machines). The firewall machine can
-still reach forbidden site(s).
-
-... start of -F rules ... # Reject and log from local net on PPP interface to
-204.50.10.13. # /sbin/ipfwadm -F -a reject -W ppp0 -S 192.168.0.0/24 -D
-204.50.10.13/32 -o # Masquerade from local net on local interface to
-anywhere. # /sbin/ipfwadm -F -a masquerade -W ppp0 -S 192.168.0.0/24 -D
-0.0.0.0/0 ... end of -F rules ...
-
-There is no need for a special rule to allow machines on the 192.168.0.0/24
-network to go to 204.50.11.0. Why? It is already covered by the global MASQ
-rule.
-
-NOTE: There is more than one way of coding the interfaces in the above rules.
-For example instead of "-V 192.168.255.1" you can code "-W eth0", instead of
-"-V $ppp_ip" , you can use "-W ppp0". The "-V" method was phased out with the
-imgration to IPCHAINS, but for IPFWADM users, its more of a personal choice
-and documentation.
------------------------------------------------------------------------------
-
-6.5. IP Masquerading multiple internal networks
-
-Masquerading more than one internal network is fairly simple. You need to
-first make sure that all of your networks are running correctly (both
-internal and external). You then need to enable traffic to pass to both the
-other internal interfaces and to be MASQed to the Internet.
-
-Next, you need to enable Masquerading on the INTERNAL interfaces. This
-example uses a total of THREE interfaces: eth0 is the EXTERNAL connection to
-the Internet, eth1 is the 192.168.0.0 network, and eth2 is the 192.168.1.0
-network. Both eth1 and eth2 will be MASQed out of interface eth0. In your
-rc.firewall ruleset next to the existing MASQ enable line, add the following:
-
-
-
- * +----------------------------------------------------------------------+
- |2.2.x kernels with IPCHAINS |
- | #Enable internal interfaces to communication between each other |
- | $IPCHAINS -A forward -i eth1 -d 192.168.0.0/24 -j ACCEPT |
- | $IPCHAINS -A forward -i eth2 -d 192.168.1.0/24 -j ACCEPT |
- | |
- | #Enable internal interfaces to MASQ out to the Internet |
- | $IPCHAINS -A forward -j MASQ -i eth0 -s 192.168.0.0/24 -d 0.0.0.0/0 |
- | $IPCHAINS -A forward -j MASQ -i eth0 -s 192.168.1.0/24 -d 0.0.0.0/0 |
- +----------------------------------------------------------------------+
-
- * +------------------------------------------------------------------+
- |2.0.x kernels with IPFWADM |
- | #Enable internal interfaces to communication between each other |
- | /sbin/ipfwadm -F -a accept -V 192.168.0.1 -D 192.168.1.0/24 |
- | /sbin/ipfwadm -F -a accept -V 192.168.1.1 -D 192.168.0.0/24 |
- | |
- | #Enable internal interfaces to MASQ out to the Internet |
- | /sbin/ipfwadm -F -a masq -W eth0 -S 192.168.0.0/24 -D 0.0.0.0/0 |
- | /sbin/ipfwadm -F -a masq -W eth0 -S 192.168.1.0/24 -D 0.0.0.0/0 |
- +------------------------------------------------------------------+
-
-
-
-
-Please note that it is CORRECT to have "eth0" specified multiple times for
-the exmples shown above. The reason for this is the Linux kernel needs to
-know which interface is used for OUTGOING traffic. Since eth0 in the above
-examples is the Internet connection, it is listed for each internal
-interface.
------------------------------------------------------------------------------
-
-6.6. IP Masquerade and Dial-on-Demand Connections
-
-
-
- 1. If you would like to setup your network to automatically dial up the
- Internet, either the Diald demand dial-up or new versions of the PPPd
- packages will be of great utility. Both Diald and PPPd are very powerful
- in their configuration flexibility.
-
- 2. To setup PPPd for Dial-on-Demand, pease check out the [http://
- www.samba.org/ppp/index.html] PPPd Homepage
-
- 3. To setup Diald, please check out the [http://diald.sourceforge.net/]
- Diald Homepage or [http://www.ecst.csuchico.edu/~dranch/LINUX/
- index-linux.html#TrinityOS] TrinityOS - Section 23
-
- 4. Once Dial on Demand and IP Masq have been setup properly, any MASQed
- client machines that initiate a web, telnet or ftp session will make the
- Linux box dynamically bring up its Internet link.
-
- 5. There is a timeout that will occur with the first connection. This is
- inevitable if you are using analog modems. The time taken to establish
- the modem link and the PPP connections may cause your client program (WWW
- browser, etc.) to stop. This isn't common though. If this does happen,
- just retry that Internet traffic request (say a WWW page) again and it
- should come up fine. You can also try setting echo "1" > /proc/sys/net/
- ipv4/ip_dynaddr kernel option to help with this initial setup.
-
-
-
------------------------------------------------------------------------------
-
-6.7. IPPORTFW, IPMASQADM, IPAUTOFW, REDIR, UDPRED, and other Port Forwarding
-tools
-
-IPPORTFW, IPAUTOFW, REDIR, UDPRED, and other programs are generic TCP and/or
-UDP port forwarding tools for Linux IP Masquerade (for < 2.4 kernels). These
-tools are typically used with or as a replacement for specific IP MASQ
-modules to get a specific network traffic through the MASQ server.
-
-With port forwarders, you can redirect data connections from the Internet to
-an internal, privately addressed machine behind your IP MASQ server. This
-forwarding ability includes network protocols such as TELNET, WWW, SMTP, FTP
-(with a special patch - see below), ICQ, and many others.
-
-NOTE: If you are just looking to do simple port forwarding but you don't need
-Masquerading support, you don't have any choice. You will STILL NEED to
-enable IP Masquerading support in the kernel AND either run a IPTABLES,
-IPCHAINS, or IPFWADM ruleset to be able to use Linux's port forwarding tools.
-
-So why all the different choices? MARK (MFW), IPMASQADM (PORTFW or AUTOFW),
-IPPORTFW, IPAUTOFW, REDIR, and UDPRED (all URLs are in Section 3.2.3) were
-the various tools available to IP MASQ users to allow this type of
-functionality. Later, as the Linux IP Masquerade feature matured, many of
-these tools were eventually replaced by the PORTFW and MARK systems which are
-more intelligent solutions.
-
-In recent 2.2.x kernels, the IPMASQADM tool combined the IPAUTOFW and
-IPPORTFW 2.0.x kernel tools into one binary. Both the IPMASQADM tool and
-IPTABLES also supports a new mechanism called "MARK" or MFW. The MARK system
-works where a specific IPTABLES or IPCHAINS ruleset would match a given
-packet sequence. Once matched, the tool would "mark" these packets. Later,
-the IPMASQADM tool or a specific IPTABLE "table" could be instructed to
-change these packets as needed and forward them off to their desired
-destination. Currently, this HOWTO doesn't cover the MARK solution but it
-will in the near future.
-
-Anyway, because of the availablity of the newer tools, it is *HIGHLY
-DISCOURAGED* to use the old tools such as IPAUTOFW (even AUTOFW in IPMASQADM)
-and REDIR because they don't properly notify the Linux kernel of their
-presence and can ultimately CRASH your Linux server with extreme use.
-
-NOTE #2: With enabling PORTFW functionality in ANY 2.2/2.0 Linux kernel (not
-2.4.x), internal machines typically CANNOT use the same "external" PORTFWed
-IP address to access a given internal" machine. To put it another way, PORTFW
-was only intended to be used with "external" computers on the Internet. If
-this is an issue for you, you can also implement the REDIR tool for 2.2.x and
-2.0.x kernels to let internal machines get redirected to the internal servers
-too. The 2.4.x kernels running IPTABLES solves this issue once and for all
-and is covered in a FAQ entry in Section 7.19. If you would like a technical
-explination on why this internal/external forwarding doesn't work, please
-page down towards the bottom of the 2.2.x PORTFW section for a note from Juan
-Jose Ciarlante.
-
-NOTE #3: The forwarding of FTP server traffic to an internal MASQed FTP
-server, known as PORTFW FTP, is now fully supported in the 2.4.x kernels as
-well as in the 2.2.x kernels via a BETA version FTP kernel module (does NOT
-come with the stock Linus kernels). It should also be noted that you can also
-PORTFW FTP traffic using an external FTP proxy program (not covered in this
-HOWTO). It should be noted that the Beta 2.2.x FTP kernel module code is
-still experimental and some people get better results simply using ACTIVE FTP
-sessions compared to PASSIVE connections. Interestingly enough, other people
-have seen the exact opposite behavior. Please let us know what your results
-are like. More about this is covered below in both the 2.2.x and 2.0.x
-sections as the solutions require the use of different patches.
-
-WARNING! Before jumping right into installing ANY of these tools, it needs to
-be mentioned that network security can be an issue with ANY PORT FORWARD
-tool. The reason for this is because these tools basically create a hole in
-strong packet firewalls for the required TCP/UDP ports. Though this doesn't
-pose any threat to your Linux machine, it might be an issue to the PORTFW'ed
-internal machine(s). No worries though, this is what Steven Clarke (the
-author of IPPORTFW) had to say about that:
-
-+---------------------------------------------------------------------------------+
-| "Port Forwarding is only called within masquerading functions so it |
-| fits inside the same IPFWADM/IPCHAINS rules. Masquerading is an extension to |
-| IP forwarding. Therefore, ipportfw only sees a packet if it fits |
-| both the input and masquerading ipfwadm rule sets." |
-+---------------------------------------------------------------------------------+
-
-What that means in English is that if you have a strong packet firewall
-running, PORTFW doesn't directly bypass any of that security. You will still
-be able to allow or deny specific IPs and/or domains to this new PORTFW'ed
-resource if you so wish.
-
-With this said, it's important to have a strong firewall ruleset. Please see
-Section 6.4.1, Section 6.4.2, and Section 6.4.3 for more details on getting
-strong rulesets.
-
- * 2.4.x kernels users should be ready to go for PORTFW functionality. 2.2.x
- and 2.0.x kernel kernel users will need to re-compile the Linux kernel to
- support PORTFW. It should be noted that some Linux distribution kernels
- might have this already done for you.
-
- * Modern 2.2.x kernel users will already have the PORTFW kernel option
- available to them via the normal kernel "make" procedures.
-
- * 2.0.x users will need to apply a simple kernel option patch to have
- access to then enable this via the normal kernel "make" procedures.
-
-
------------------------------------------------------------------------------
-6.7.1. 2.4.x PORTFWD'ing: Using IPTABLE's PREROUTING option for 2.4.x kernels
-
-Unlike ALL previous Linux kernels, the 2.4.x series now allows for full
-PORTFW, PORTFW FTP, and PORTFW REDIR functionality within the "iptables" tool
-itself.
-
-NOTE: Once you enable a port forwarder on say port 80 (forward WWW traffic
-through the MASQ server to an internal WWW server), that port will no longer
-be used by the Linux IP Masquerade server itself. To be more specific, if you
-have a WWW server already running on the MASQ server, enabling PORTFW will
-now give all Internet users acces to the WWW pages from the -INTERNAL- WWW
-server and not the pages on your IP MASQ server.
-
-To enable port forwarding on a 2.4.x kernel:
-
- * Edit the /etc/rc.d/rc.firewall-2.4 ruleset and place the lines shown
- below just ABOVE the "FWD: Allow all connections OUT and only existing
- and related ones IN" line (in the "Optional FORWARD section"). Please be
- sure to replace the word "$EXTIP" with your specific Internet IP address.
-
- * NOTE: Unlike the 2.2.x and 2.0.x kernels, PORTFWed traffic does *not*
- traverse the INPUT or OUTPUT rules. It only traverses the FORWARD rule.
-
-
- * NOTE: If you use get a DYNAMIC TCP/IP address from your ISP (PPP, ADSL,
- Cablemodems, etc.), you will NEED to make your /etc/rc.d/rc.firewall
- ruleset more intelligent. To do this, please see Section 6.4.2 from above
- or [http://www.ecst.csuchico.edu/~dranch/LINUX/index-linux.html#
- TrinityOS] TrinityOS - Section 10 for more details on strong rulesets and
- Dynamic IP addresses. I'll give you a hint though: /etc/ppp/ip-up for PPP
- users.
-
-
- /etc/rc.d/rc.firewall
-+---------------------------------------------------------------------------+
-|#echo "Enabling PORTFW Redirection on the external LAN.." |
-|# |
-|# This will forward ALL port 80 traffic from the external IP address |
-|# to port 80 on the 192.168.0.10 machine |
-|# |
-|# Be SURE that when you add these new rules to your rc.firewall, you |
-|# add them before a direct or implict DROP or REJECT. |
-|# |
-|PORTFWIP="192.168.0.10" |
-| |
-| |
-|# NOTE: If you are using the basic rc.firewall-2.4 ruleset, you |
-|# will need to enable the following EXTIP option. Users of the |
-|# rc.firewall-2.4-stronger ruleset already have this defined. |
-|# |
-|# *PLEASE* look over the rc.firewall-2.4-stronger ruleset for more |
-|# specific issues regarding dynamic vs. static IP addresses |
-|# |
-|# |
-|# Determine the external IP automatically: |
-|# ---------------------------------------- |
-|# |
-|# The following line will determine your external IP address. This |
-|# line is somewhat complex and confusing but it will also work for |
-|# all NON-English Linux distributions: |
-|# |
-|# DISABLED by default -- to enable, REMOVE both the "#" characters below |
-|# |
-|#EXTIP="`$IFCONFIG $EXTIF | $AWK \ |
-|# /$EXTIF/'{next}//{split($0,a,":");split(a[2],a," ");print a[1];exit}'`" |
-| |
-| |
-|# Allow forwarding of new and existing port 80 connections |
-|# |
-|$IPTABLES -A FORWARD -i $EXTIF -o $INTIF -p tcp --dport 80 -m state \ |
-| --state NEW,ESTABLISHED,RELATED -j ACCEPT |
-| |
-|#Enable PORTFW of this port 80 traffic |
-|# |
-|$IPTABLES -A PREROUTING -t nat -p tcp -d $EXTIP --dport 80 \ |
-| -j DNAT --to $PORTFWIP:80 |
-+---------------------------------------------------------------------------+
-
-
-That's it! Just re-run your /etc/rc.d/rc.firewall-2.4 ruleset and test it
-out!
-
---------------------------------------------------------------------------
-
-Running the rc.firewall-2.4-stronger ruleset? Good for you! To get PORTFW
-running with this ruleset, it's very easy. The following example is for HTTP
-(WWW) traffic to be PORTFWed to the IP address indicated by the $PORTFWIP
-variable:
-
- * Take the ruleset lines shown above (for the generic rc.firewall ruleset)
- and place them just after the "#FORWARD Enable Forwarding and thus
- IPMASQ" comment lines. It should also be noted that you DO NOT have to
- enable the "HTTPD" rules under the "Optional 'INPUT' section" for
- 2.4-based kernels. With 2.4 kernels, those lines are ONLY used if you
- want to allow HTTP traffic to terminate on the MASQ server's httpd
- process (Apache).
-
-
-PORTFW FTP: If you have the "ip_conntrack_ftp" and "ip_nat_ftp" kernel
-modules loaded into kernel space (as already done in the rc.firewall-2.4
-script), the simple PREROUTING command like the one shown above changed for
-for port "21" should do the trick. This is much easier than the configuration
-for the old 2.2.x / 2.0.x kernels!
-
-Please note, if you setup PORTFW to an internal FTP server that is running on
-a NON-standard FTP port, say port 8021, you MUST tell the "ip_conntrack_ftp"
-module about the new FTP port. The reason for this is that FTP is not a
-NAT-friendly protocol. By telling the NAT module about this new non-standard
-FTP port, the NAT module and do it's job again. To do this, edit your
-rc.firewall file and change the loading of the FTP module to look something
-like this:
-
-+---------------------------------------------------------------------------+
-|/sbin/insmod ip_conntrack_ftp ports=21,8021 |
-+---------------------------------------------------------------------------+
-
-PORTFW Redirection of Internal requests:
-
-In the past, if users PORTFWed port 80 on their EXTERNAL IP address to some
-internal machine, only machines out on the Internet would properly reach this
-internal WWW server. If you tried to contact this internal WWW server via the
-MASQ server's EXTERNAL address, it would fail. Fortunately, there is a
-workaround for 2.2.x and 2.0.x kernels using the REDIR tool. Even better, the
-use of the REDIR tool is NOT required for the 2.4.x kernels. To support
-redirection like this from an internal host, add a rule like the one shown
-below ABOVE the "Catch all" FORWARDing rule in the rc.firewall file. The
-following example will REDIRECT internal WWW traffic to the 192.168.0.2
-internal machine (please change the IP address to reflect your
-configuration):
-
-+---------------------------------------------------------------------------+
-|$IPTABLES -t nat -A PREROUTING -d $EXTIP -p tcp --dport 80 \ |
-| -m state --state NEW,ESTABLISHED,RELATED -j DNAT --to 192.168.0.2 |
-+---------------------------------------------------------------------------+
------------------------------------------------------------------------------
-
-6.7.2. 2.2.x PORTFWD'ing: Using IPMASQADM with 2.2.x kernels
-
-First, make sure you have the newest 2.2.x kernel uncompressed into /usr/src/
-kernel/linux. If you haven't already done this, please see Section 3.2.2
-section for full details. Next, download the "ipmasqadm.c" program from
-Section 2.7 into the /usr/src/kernel directory.
-
-Next, you'll need to compile the 2.2.x kernel as shown in Section 3.2.2
-section. Be sure to say "YES" to the IPPORTFW option when you configure the
-kernel. Once the kernel compile is complete and you have rebooted, return to
-this section.
-
-Now, compile and install the IPMASQADM tool:
-
-+---------------------------------------------------------------------------+
-| cd /usr/src |
-| tar xzvf ipmasqadm-x.tgz |
-| cd ipmasqadm-x |
-| make |
-| make install |
-+---------------------------------------------------------------------------+
-
-Now, for this example, we are going to allow ALL WWW Internet traffic (port
-80) hitting your Internet TCP/IP address to be forwarded to the internal
-Masqueraded machine at IP address 192.168.0.10.
-
-PORTFW FTP: As mentioned above, there are two solutions for forwarding FTP
-server traffic to an internal MASQed PC. The first solution *IS* a BETA level
-IP_MASQ_FTP module for 2.2.x kernels to PORT Forward FTP connections to an
-internal MASQed FTP server. The other method is using a FTP proxy program
-(the URL is in Section 2.7. It should also be noted that the FTP kernel
-module also supports the adding of additional PORTFW FTP ports on the fly
-without the requirement of unloading and reloading the IP_MASQ_FTP module and
-thus breaking any existing FTP transfers. You can find more about this new
-code at the IPMASQ WWW site at [http://ipmasq.webhop.net] http://
-ipmasq.webhop.net;. There are also examples and some additional information
-about PORTFWed FTP connection below in the 2.0.x. kernel section.
-
-NOTE: Once you enable a port forwarder on port 80, that port can no longer be
-used by the Linux IP Masquerade server. To be more specific, if you have a
-WWW server already running on the MASQ server, a port forward will now give
-all Internet users the WWW pages from the -INTERNAL- WWW server and not the
-pages on your IP MASQ server.
-
-Anyway, to enable port forwarding for HTTPd:
-
- * Edit the /etc/rc.d/rc.firewall ruleset and ENABLE the "Optional" "HTTP"
- sections in both the INPUT and OUTPUT subsections.
-
- * Add the following lines shown below JUST BELOW the "ipchains -P forward
- DENY" rule (in the "Optional FORWARD section"). Be sure to replace the
- "$EXTIP" variable's contents with your EXTERNAL Internet IP address on
- the IPMASQ server.
-
-
-NOTE: If you use get a DYNAMIC TCP/IP address from your ISP (PPP, ADSL,
-Cablemodems, etc.), you will NEED to make your /etc/rc.d/rc.firewall ruleset
-more intelligent. To do this, please see Section 6.4.2 from above or [http://
-www.ecst.csuchico.edu/~dranch/LINUX/index-linux.html#TrinityOS] TrinityOS -
-Section 10 for more details on strong rulesets and Dynamic IP addresses. I'll
-give you a hint though: /etc/ppp/ip-up for PPP users.
-
- /etc/rc.d/rc.firewall
-+---------------------------------------------------------------------------+
-|#echo "Enabling IPPORTFW Redirection on the external LAN.." |
-|# |
-|# This will forward ALL port 80 traffic from the external IP address |
-|# to port 80 on the 192.168.0.10 machine |
-|# |
-|PORTFWIP="192.168.0.10" |
-| |
-|/usr/sbin/ipmasqadm portfw -f |
-|/usr/sbin/ipmasqadm portfw -a -P tcp -L $EXTIP 80 -R $PORTFWIP 80 |
-+---------------------------------------------------------------------------+
-
-
-That's it! Just re-run your /etc/rc.d/rc.firewall ruleset and test it out!
-
-If you get the error message "ipchains: setsockopt failed: Protocol not
-available", you AREN'T running your new IPPORTFW enabled kernel. Make sure
-that you moved the new kernel over, re-run LILO, and then reboot again. If
-you are sure you are running your new kernel, run the command "ls /proc/net/
-ip_masq" and make sure the "portfw" file exists. If it doesn't, you must have
-made an error when configuring your kernel. Try again.
-
-For those who want to understand why PORTFW cannot redirect traffic for both
-external and internal interfaces (the REDIR situation), here is an email from
-Juanjo that better explains it:
-
-
-From Juanjo Ciarlante
---
-
->If I use:
->
-> ipmasqadm portfw -a -P tcp -L 1.2.3.4 80 -R 192.168.2.3 80
->
->Everything works great from the outside but internal requests for the same
->1.2.3.4 address fail. Are there chains that will allow a machine on localnet
->192.168.2.0 to accesss www.periapt.com without using a proxy?
-
-Actually not.
-
-I usually setup a ipmasqadm rule for outside, *AND* a port
-redirector for inside. This works because ipmasqadm hooks before
-redir will get the eventual outside connection, _but_ leaves things
-ok if not (stated by APPROPIATE rules).
-
-The actual "conceptual" problem comes from the TRUE client (peer) IP
-goal (thanks to masq) being in the same net as target server.
-
-The failing scenario for "local masq" is :
- client: 192.168.2.100
- masq: 192.168.2.1
- serv: 192.168.2.10
-
-1)client->server packet
- a) client: 192.168.2.100:1025 -> 192.168.2.1:80 [SYN]
- b) (masq): 192.168.2.100:1025 -> 192.168.2.10:80 [SYN]
- (and keep 192.168.2.1:61000 192.168.2.100:1025 related)
- c) serv: gets masqed packet (1b)
-
-2)server->client packet
- a) serv: 192.168.2.10:80 -> 192.168.2.100:1025 [SYN,ACK]
- b) client: 192.168.2.100:1025 -> 192.168.2.10:80 [RST]
-
-Now take a moment to compare (1a) with (2a).
-You see, the server replied DIRECTLY to client bypassing masq (not
-letting masq to UNDO the packet hacking) because it is in SAME net, so
-the client resets the connection.
-
-hope I helped.
-
-Warm regards
-Juanjo
-
------------------------------------------------------------------------------
-
-6.7.3. 2.0.x PORTFWD'ing: Using IPPORTFW on 2.0.x kernels
-
-First, make sure you have the newest 2.0.x kernel uncompressed into /usr/src/
-kernel. If you haven't already done this, please see Section 3.2.3 for full
-details. Next, download the "ipportfw.c" program and the "subs-patch-x.gz"
-kernel patch from Section 3.2.3 into the /usr/src/ directory.
-
-NOTE: Please replace the "x" in the "subs-patch-x.gz" file name with the most
-current version available on the site.
-
-Next, if you plan on port forwarding FTP traffic to an internal server, you
-will have to apply an additional NEW IP_MASQ_FTP module patch found in
-Section 3.2.3. More details regarding this are later in this section. Please
-note that this is NOT the same patch as for the 2.2.x kernels so some
-functionality such as the dynamic FTP PORT functionality is not present.
-
-Now, copy the IPPORTFW patch (subs-patch-x.gz) into the Linux directory
-+---------------------------------------------------------------------------+
-| cp /usr/src/subs-patch-1.37.gz /usr/src/linux |
-+---------------------------------------------------------------------------+
-
-Next, apply the kernel patch to create the IPPORTFW kernel option:
-+---------------------------------------------------------------------------+
-| cd /usr/src/linux |
-| zcat subs-patch-1.3x.gz | patch -p1 |
-+---------------------------------------------------------------------------+
-
-Ok, time to compile the kernel as shown in Section 3.2.3. Be sure to say YES
-to the IPPORTFW option now available when you configure the kernel. Once the
-compile is complete and you have rebooted, return to this section.
-
-Now with a newly compiled kernel, please compile and install the actual
-"IPPORTFW" program
-+---------------------------------------------------------------------------+
-| cd /usr/src |
-| gcc ipportfw.c -o ipportfw |
-| mv ipportfw /usr/local/sbin |
-+---------------------------------------------------------------------------+
-
-Now, for this example, we are going to allow ALL WWW Internet traffic (port
-80) hitting your Internet TCP/IP address to then be forwarded to the internal
-Masqueraded machine at IP address 192.168.0.10.
-
-NOTE: Once you enable a port forwarder on port 80, that port can no longer be
-used by the Linux IP Masquerade server. To be more specific, if you have a
-WWW server already running on the MASQ server and then you port forward port
-80 to an internal MASQed computer, ALL internet users will see the WWW pages
-pages from the -INTERNAL- WWW server and not the pages on your IP MASQ
-server. This only performs a port forward to some other port, say 8080, to
-your internal MASQ machine. Though this will work, all Internet users will
-have to append :8080 to the URL to then contact the internal MASQed WWW
-server.
-
-Anyway, to enable port forwarding, edit the /etc/rc.d/rc.firewall ruleset.
-Add the follow lines but be sure to replace the word "$extip" with your
-Internet IP address.
-
-NOTE: If you use get a DYNAMIC TCP/IP address from your ISP (PPP, ADSL,
-Cablemodems, etc.), you will NEED to make your /etc/rc.d/rc.firewall ruleset
-more intelligent. To do this, please see Section 6.4.2from above or [http://
-www.ecst.csuchico.edu/~dranch/LINUX/index-linux.html#TrinityOS] TrinityOS -
-Section 10 for more details on strong rulesets and Dynamic IP addresses. I'll
-give you a hint though: /etc/ppp/ip-up for PPP users.
-
-/etc/rc.d/rc.firewall
-+---------------------------------------------------------------------------+
-|#echo "Enabling IPPORTFW Redirection on the external LAN.." |
-|# |
-|# This will forward ALL port 80 traffic from the external IP address |
-|# to port 80 on the 192.168.0.10 machine |
-|# |
-|/usr/local/sbin/ipportfw -C |
-|/usr/local/sbin/ipportfw -A -t$extip/80 -R 192.168.0.10/80 |
-+---------------------------------------------------------------------------+
-
-That's it! Just re-run your /etc/rc.d/rc.firewall ruleset and test it out!
-
-If you get the error message "ipfwadm: setsockopt failed: Protocol not
-available", you AREN'T running your new kernel. Make sure that you moved the
-new kernel over, re-run LILO, and then reboot again.
-
-Port Forwarding FTP servers:
-
-If you plan on port forwarding FTP to an internal machine, things get more
-complicated. The reason for this is because the standard IP_MASQ_FTP kernel
-module wasn't written for this though some users report that it works without
-any problems. Personally, without the patch, I've heard that extended file
-transfers in excess of 30 minutes will fail without the patch while other
-users swear that it works flawlessly. Anyway, I recommend that you try the
-following PORTFW instruction with the STOCK ip_masq_ftp module and see if it
-works for you. If it doesn't, try using the modified ip_masq_ftp module.
-
-For those who need the module, Fred Viles wrote a modified IP_MASQ_FTP module
-to make things work. If you are curious what EXACTLY are the issues, download
-the following archive since Fred documents it quite well. Also understand
-that this patch is somewhat experimental and should be treated as such. It
-should be noted that this patch is ONLY available for the 2.0.x kernels
-though there is a different patch available for 2.2.x kernels.
-
-So, to get the 2.0.x patch working, you need to:
-
-
-
- * FIRST, apply the IPPORTFW kernel patch as shown earlier in this section.
-
- * Download the "msqsrv-patch-36" from Fred Viles's FTP server in Section
- 3.2.3and put it into /usr/src/linux.
-
- * Patch the kernel with this new code by running "cat msqsrv-patch-36 |
- patch -p1"
-
- * Next, replace the original "ip_masq_ftp.c" kernel module with the new one
-
- mv /usr/src/linux/net/ipv4/ip_masq_ftp.c /usr/src/linux/net/ipv4/
- ip_masq_ftp.c.orig
-
- mv /usr/src/linux/ip_masq_ftp.c /usr/src/linux/net/ipv4/ip_masq_ftp.c
-
- * Lastly, build and install the kernel with this new code in place.
-
-
-
-
-Once this is complete, edit the /etc/rc.d/rc.firewall ruleset and add the
-following lines, but be sure to replace the word "$extip" with your Internet
-IP address.
-
-This example, like the one above, will allow ALL FTP Internet traffic (port
-21) hitting your Internet TCP/IP address to then be forwarded to the internal
-Masqueraded machine at IP address 192.168.0.10.
-
-NOTE: Once you enable a port forwarder on port 21, that port can no longer be
-used by the Linux IP Masquerade server. To be more specific, if you have an
-FTP server already running on the MASQ server, a port forward will now give
-all Internet users the FTP files from the -INTERNAL- FTP server and not the
-files on your IP MASQ server.
-
-/etc/rc.d/rc.firewall
-+---------------------------------------------------------------------------+
-|#echo "Enabling IPPORTFW Redirection on the external LAN.." |
-|# |
-|/usr/local/sbin/ipportfw -C |
-|/usr/local/sbin/ipportfw -A -t$extip/21 -R 192.168.0.10/21 |
-| |
-|#NOTE: If you are using multiple local port numbers to PORTFW |
-|# to multuple internal FTP servers (say, 21, 2121, 2112, |
-|# etc, you need to configure the ip_masq_ftp nodule to |
-|# listen to these ports. To do this, edit the |
-|# /etc/rc.d/rc.firewall script as shown in this HOWTO |
-|# to look like: |
-|# |
-|# /sbin/modprobe ip_masq_ftp ports=21,2121,2112 |
-|# |
-|# Re-run the /etc/rc.d/rc.firewall script for these changes to |
-|# take effect. |
-| |
-| |
-|#Please note that PORTFWing port 20 is probably NOT required |
-|# for ACTIVE connections as the internal FTP server will |
-|# initiate this port 20 connection and it will be properly |
-|# handled by the classic MASQ mechanisms. |
-+---------------------------------------------------------------------------+
-
-That's it! Just re-run your /etc/rc.d/rc.firewall ruleset and test it out!
------------------------------------------------------------------------------
-
-6.8. CU-SeeMe and Linux IP-Masquerade
-
-Linux IP Masquerade supports CuSeeme via the "ip_masq_cuseeme" kernel module.
-This kernel modules should be loaded in the /etc/rc.d/rc.firewall script.
-Once the "ip_masq_cuseeme" module is installed, you should be able to both
-initiate and receive CuSeeme connections to remote reflectors and/or users.
-
-NOTE: It is recommended to use the IPPORTFW tool instead of the old IPAUTOFW
-tool for running CuSeeme.
-
-If you need more explicit information on configuring CuSeeme, see Michael
-Owings's CuSeeMe page for a Mini-HOWTO or The IP Masquerade Resources for a
-mirror of the Mini-HOWTO.
------------------------------------------------------------------------------
-
-6.9. Mirabilis ICQ
-
-ICQ, the instant messaging client now owned by AOL, has changed over the
-years. All modern ICQ clients are NAT friendly and thus DON'T require any
-special NAT modules, PORTFW tricks, etc.
-
-IF, for some reason, you want to run an OLD ICQ client, you can read this
-section. If not, just IGNORE all this info. I am leaving this in the HOWTO
-demonstrate large a LARGE PORTFW example.
-
-There are three methods of getting ICQ to work behind a Linux MASQ server.
-These solutions include the use the ICQ Masq module (for 2.2.x and 2.0.x
-kernels), using IPPORTFW for basic ICQ functionality, or setting up a SOCKS
-proxy server.
-
-MODULE: The ICQ module was written for the older generation of ICQ clients
-for both the 2.2.x and 2.0.x kernels. This module allows for the simple setup
-of multiple ICQ users behind a MASQ server. It also doesn't require any
-special changes to the ICQ client(s). Recently, AOL changed the protocol and
-ports used for ICQ. Because of this, many users might find that the
-ip_masq_icq module will no longer help them. For users of the older ICQ
-clients, the 2.2.x version of the module supports file transfer and read-time
-chat. The 2.0.x kernel module doesn't support file transfers and there is no
-module available for the 2.4.x kernels.
-
-PORTFW: Your next option is to use port forwarding. With port forwarding,
-basic ICQ chat will work but file transfers might not be very reliable.
-Please see below for an example of how to configure ICQ PORTFW.
-
-SOCKS: Finally, your last and possibly best option is to setup a SOCKS proxy
-server on your Linux machine. This service can happily co-exist with the MASQ
-service and ICQ should be fully functional regardless of what Linux kernel
-version you are running. The use of a SOCKS server will require ALL ICQ
-clients to be reconfigured to use it and the installation and configuration
-of a SOCKS server has nothing to do with IP Masquerade. Because of this,
-SOCKS is not covered in this HOWTO.
-
-If you are interested in Andrew Deryabin's [mailto:djsf@usa.net] djsf@usa.net
-ICQ IP Masq module for the 2.2.x and 2.0.x kernels, please see Section 2.7
-for details.
-
-To use port forwarding (PORFW)for ICQ, you will have to make some changes on
-both Linux and ICQ clients but all ICQ messaging, URLs, chat, and some file
-transfers should work.
-
- * First, you need to be running a Linux kernel with IPPPORTFW enabled.
- Please see Section 6.7for more details.
-
- * Next, you need to add the following lines to your /etc/rc.d/rc.firewall
- file. This example assumes that 10.1.2.3 is your external Internet IP
- address and your internal MASQed ICQ machine is 192.168.0.10:
-
- * The following example is for a 2.2.x kernel with IPCHAINS:
-
- I have included two examples here for the user: Either one would work
- fine:
-
- Example #1
- /usr/local/sbin/ipmasqadm portfw -a -P tcp -L 10.1.2.3 2000 -R 192.168.0.10 2000
- /usr/local/sbin/ipmasqadm portfw -a -P tcp -L 10.1.2.3 2001 -R 192.168.0.10 2001
- /usr/local/sbin/ipmasqadm portfw -a -P tcp -L 10.1.2.3 2002 -R 192.168.0.10 2002
- /usr/local/sbin/ipmasqadm portfw -a -P tcp -L 10.1.2.3 2003 -R 192.168.0.10 2003
- /usr/local/sbin/ipmasqadm portfw -a -P tcp -L 10.1.2.3 2004 -R 192.168.0.10 2004
- /usr/local/sbin/ipmasqadm portfw -a -P tcp -L 10.1.2.3 2005 -R 192.168.0.10 2005
- /usr/local/sbin/ipmasqadm portfw -a -P tcp -L 10.1.2.3 2006 -R 192.168.0.10 2006
- /usr/local/sbin/ipmasqadm portfw -a -P tcp -L 10.1.2.3 2007 -R 192.168.0.10 2007
- /usr/local/sbin/ipmasqadm portfw -a -P tcp -L 10.1.2.3 2008 -R 192.168.0.10 2008
- /usr/local/sbin/ipmasqadm portfw -a -P tcp -L 10.1.2.3 2009 -R 192.168.0.10 2009
- /usr/local/sbin/ipmasqadm portfw -a -P tcp -L 10.1.2.3 2010 -R 192.168.0.10 2010
- /usr/local/sbin/ipmasqadm portfw -a -P tcp -L 10.1.2.3 2011 -R 192.168.0.10 2011
- /usr/local/sbin/ipmasqadm portfw -a -P tcp -L 10.1.2.3 2012 -R 192.168.0.10 2012
- /usr/local/sbin/ipmasqadm portfw -a -P tcp -L 10.1.2.3 2013 -R 192.168.0.10 2013
- /usr/local/sbin/ipmasqadm portfw -a -P tcp -L 10.1.2.3 2014 -R 192.168.0.10 2014
- /usr/local/sbin/ipmasqadm portfw -a -P tcp -L 10.1.2.3 2015 -R 192.168.0.10 2015
- /usr/local/sbin/ipmasqadm portfw -a -P tcp -L 10.1.2.3 2016 -R 192.168.0.10 2016
- /usr/local/sbin/ipmasqadm portfw -a -P tcp -L 10.1.2.3 2017 -R 192.168.0.10 2017
- /usr/local/sbin/ipmasqadm portfw -a -P tcp -L 10.1.2.3 2018 -R 192.168.0.10 2018
- /usr/local/sbin/ipmasqadm portfw -a -P tcp -L 10.1.2.3 2019 -R 192.168.0.10 2019
- /usr/local/sbin/ipmasqadm portfw -a -P tcp -L 10.1.2.3 2020 -R 192.168.0.10 2020
-
- Example #2
- port=2000
- while [ $port -le 2020 ]
- do
- /usr/local/sbin/ipmasqadm portfw -a -P tcp -L 10.1.2.3 $port -R 192.168.0.10 $port
- port=$((port+1))
- done
-
-
- * The following example is for a 2.0.x kernel with IPFWADM:
-
- I have included two examples here for the user: Either one would work
- fine:
-
- Example #1
- /usr/local/sbin/ipportfw -A -t10.1.2.3/2000 -R 192.168.0.10/2000
- /usr/local/sbin/ipportfw -A -t10.1.2.3/2001 -R 192.168.0.10/2001
- /usr/local/sbin/ipportfw -A -t10.1.2.3/2002 -R 192.168.0.10/2002
- /usr/local/sbin/ipportfw -A -t10.1.2.3/2003 -R 192.168.0.10/2003
- /usr/local/sbin/ipportfw -A -t10.1.2.3/2004 -R 192.168.0.10/2004
- /usr/local/sbin/ipportfw -A -t10.1.2.3/2005 -R 192.168.0.10/2005
- /usr/local/sbin/ipportfw -A -t10.1.2.3/2006 -R 192.168.0.10/2006
- /usr/local/sbin/ipportfw -A -t10.1.2.3/2007 -R 192.168.0.10/2007
- /usr/local/sbin/ipportfw -A -t10.1.2.3/2008 -R 192.168.0.10/2008
- /usr/local/sbin/ipportfw -A -t10.1.2.3/2009 -R 192.168.0.10/2009
- /usr/local/sbin/ipportfw -A -t10.1.2.3/2010 -R 192.168.0.10/2010
- /usr/local/sbin/ipportfw -A -t10.1.2.3/2011 -R 192.168.0.10/2011
- /usr/local/sbin/ipportfw -A -t10.1.2.3/2012 -R 192.168.0.10/2012
- /usr/local/sbin/ipportfw -A -t10.1.2.3/2013 -R 192.168.0.10/2013
- /usr/local/sbin/ipportfw -A -t10.1.2.3/2014 -R 192.168.0.10/2014
- /usr/local/sbin/ipportfw -A -t10.1.2.3/2015 -R 192.168.0.10/2015
- /usr/local/sbin/ipportfw -A -t10.1.2.3/2016 -R 192.168.0.10/2016
- /usr/local/sbin/ipportfw -A -t10.1.2.3/2017 -R 192.168.0.10/2017
- /usr/local/sbin/ipportfw -A -t10.1.2.3/2018 -R 192.168.0.10/2018
- /usr/local/sbin/ipportfw -A -t10.1.2.3/2019 -R 192.168.0.10/2019
- /usr/local/sbin/ipportfw -A -t10.1.2.3/2020 -R 192.168.0.10/2020
-
-
- Example #2
- port=2000
- while [ $port -le 2020 ]
- do
- /usr/local/sbin/ipportfw -A t10.1.2.3/$port -R 192.168.0.10/$port
- port=$((port+1))
- done
-
-
- * Once your new rc.firewall is ready, reload the ruleset to make sure
- things are OK by simply typing in "/etc/rc.d/rc.firewall". If you get any
- errors, you either don't have IPPORTFW support in the kernel or you made
- a typo in the rc.firewall file.
-
- * Now, in ICQ's Preferences-->Connection, configure it to be "Behind a LAN"
- and "Behind a firewall or Proxy". Now, click on "Firewall Settings" and
- configure it to be "I don't use a SOCK5 proxy". Also note that it was
- previously recommended to change ICQ's "Firewall session timeouts" to
- "30" seconds BUT many users have found that ICQ becomes unreliable. It
- has been found that ICQ is more reliable with its stock timeout setting
- (don't enable that ICQ option) and simply change MASQ's timeout to 160
- seconds. You can see how to change this timeout in Section 3.4.3 and
- Section 3.4.2 rulesets. Finally, click on Next and configure ICQ to "Use
- the following TCP listen ports.." from "2000" to "2020". Now click done.
-
- Now ICQ will tell you that you will have to restart ICQ for the changes
- to take effect. To be honest, I had to REBOOT the Windows9x machine in
- order for things to work right but some users might say otherwise. So..
- try it both ways.
-
- * A user once told me that by simply portforwarding port 4000 to his ICQ
- machine, it worked perfectly. He reported that EVERYTHING worked fine
- (even chat, file transfers, etc) WITHOUT re-configuring ICQ from its
- default settings. Your mileage might vary on this topic but I thought you
- might like to hear about this alternative configuration.
-
-
------------------------------------------------------------------------------
-6.10. Gamers: The LooseUDP patch
-
-The LooseUDP patch allows semi-NAT-friendly games that usually use UDP
-connections to both WORK behind a Linux IP Masquerade server.
-
-What the LooseUDP patch does is allow ALL UDP packets to be NATed through the
-MASQ box without any checks or expiration. This liberal forwarding method is
-considered insecure by many and is disabled in modern 2.2.x kernels. The
-2.4.x kernels with it's IPTABLES stateful UDP inspection only allows incoming
-UDP packets into the machine (and thus MASQ) if there was already an outbound
-UDP packet to that same host in it's stateful table. If the MASQ host hasn't
-sent a UDP packet to the remote host within ~30 seconds, the return UDP table
-entry is deleted. Because of this, IPTABLES removes most of the need for the
-LooseUDP patch as it does it in a more secure fashion.
-
-Currently, LooseUDP is available as a patch for 2.0.36+ kernels and it is
-already built into 2.2.3+ kernels though it is now DISABLED by DEFAULT in
-2.2.16+ (please see the example rc.firewal ruleset comments for details).
-
-To get LooseUDP running on a 2.0.x kernel, follow the following steps:
-
- * Have the newest 2.0.x kernel sources uncompressed in the /usr/src/linux
- directory
-
- * ABSOLUTELY REQUIRED for v2.0.x: Download and install the IPPORTFW patch
- from Section 3.2.3and as described in Section 6.7of the HOWTO.
-
- * Download the LooseUDP patch from Section 3.2.3
-
- Now, put the LooseUDP patch in the /usr/src/linux directory. Once this is
- done, type in:
-
- +------------------------------------------------------------------------+
- |For a compressed patch file: zcat loose-udp-2.0.36.patch.gz | patch -p1|
- +------------------------------------------------------------------------+
-
- +------------------------------------------------------------------------+
- |For a NON-compressed patch file: cat loose-udp-2.0.36.patch | patch -p1|
- +------------------------------------------------------------------------+
-
- Now, depending on the version of your "patch", You will then see the
- following text:
-
- +---------------------------------------------------------------+
- |patching file `CREDITS' |
- |patching file `Documentation/Configure.help' |
- |patching file `include/net/ip_masq.h' |
- |patching file `net/ipv4/Config.in' |
- |patching file `net/ipv4/ip_masq.c' |
- +---------------------------------------------------------------+
-
- * If you see the text "Hunk FAILED" only ONCE and ONLY ONCE at the very
- beginning of the patching, don't be alarmed. You probably have an old
- patch file (this has been fixed) but it still works. If it fails
- completely, make sure you have applied the IPPORTFW kernel patch FIRST.
-
- Once the patch is installed, re-configure the kernel as shown in Section
- 3.2.3 and be sure to say "Y" to the "IP: loose UDP port managing
- (EXPERIMENTAL) (CONFIG_IP_MASQ_LOOSE_UDP) [Y/n/?]" option.
-
-
-
-
-To get LooseUDP running on a 2.2.x kernel, follow the following steps:
-
- * In the /etc/rc.d/rc.firewall script, goto the BOTTOM of the file and find
- the LooseUDP section. Change the "0" in the line: echo "0" > /proc/sys/
- net/ipv4/ip_masq_udp_dloose to a "1" and re-run the rc.firewall ruleset.
- An example of this is given in both Section 3.4.2 example and Section
- 6.4.3 example.
-
-
-
-
-NOTE: The LooseUDP code is /not/ available (?required?) for the 2.4.x kernels
-
- * See the begining of this section for all the details. Basically, the old
- 2.0.x / 2.2.x LooseUDP code was considered a security issue. Because of
- this, it was removed from the kernel. Fortunately, some games that used
- to require the LooseUDP code on the 2.2.x IPCHAINS system might work just
- final under the 2.4.x IPTABLES kernels. If the games don't work, I'm not
- aware of a solution for you. Sorry.
-
-
-Once you are running the new LooseUDP enabled kernel, you should be good to
-go for most NAT-friendly games. Some URLs have been given for patches to make
-games like BattleZone and others NAT friendly. Please see Section 6.3.1 for
-more details.
------------------------------------------------------------------------------
-
-Chapter 7. Frequently Asked Questions
-
-If you can think of any useful FAQ suggestions, please send it to [mailto:
-dranch@trinnet.net] dranch@trinnet.net. Please clearly state the question and
-an appropriate answer (if you have it). Thank you!
------------------------------------------------------------------------------
-
-7.1. ( Distro ) - What Linux Distributions support IP Masquerading?
-
-If your Linux distribution doesn't support IP MASQ out of the box, don't
-worry. All you have to do is to re-compile the kernel as shown above in this
-HOWTO.
-
-NOTE: If you can help us fill out this table, please email [mailto:
-dranch@trinnet.net] dranch@trinnet.net.
-
-
-
- * Caldera < v1.2 : NO - ?
-
- * Caldera v1.3 : YES - 2.0.35 based
-
- * Caldera v2.2 : YES - 2.2.5 based
-
- * Caldera eServer v2.3 : YES - ? based
-
- * Debian v1.3 : NO - ?
-
- * Debian v2.0 : NO - ?
-
- * Debian v2.1 : YES - 2.2.1 based
-
- * Debian v2.2 : YES - 2.2.15 based
-
- * Debian v3.0 : YES - 2.4.18 based
-
- * DLX Linux v? : ? - ?
-
- * DOS Linux v? : ? - ?
-
- * FloppyFW v1.0.2 : ? - ?
-
- * Gentoo v1.4 : YES - ? Based
-
- * Hal91 Linux v? : ? - ?
-
- * Linux PPC vR4 : NO - ?
-
- * Linux Pro v? : ? - ?
-
- * LinuxWare v? : ? - ?
-
- * Mandrake v5.3 : YES - ?
-
- * Mandrake v6.0 : YES - 2.2.5
-
- * Mandrake v6.1 : YES - ?
-
- * Mandrake v7.0 : YES - 2.2.14
-
- * Mandrake v7.1 : YES - 2.2.15
-
- * Mandrake v7.2 : YES - 2.2.17
-
- * Mandrake v8.0 : YES - ?
-
- * Mandrake v8.1 : YES - 2.4.8
-
- * Mandrake v8.2 : YES - ?
-
- * Mandrake v9.0 : YES - ?
-
- * Mandrake v9.1 : YES - 2.4.21-pre
-
- * MkLinux v? : ? - ?
-
- * MuLinux v3rl : YES - ?
-
- * Redhat < v4.x : NO - ?
-
- * Redhat v5.0 : YES - ?
-
- * Redhat v5.1 : YES - 2.0.34 based
-
- * Redhat v5.2 : YES - 2.0.36 based
-
- * Redhat v6.0 : YES - 2.2.5 based
-
- * Redhat v6.1 : YES - 2.2.12 based
-
- * Redhat v6.2 : YES - 2.2.14 based
-
- * Redhat v7.0 : YES - 2.2.16 based
-
- * Redhat v7.2 : YES - 2.4.7 based
-
- * Redhat v7.3 : YES - 2.4.? based
-
- * Redhat v8.0 : YES - 2.4.18? based
-
- * Slackware v3.0 : ? - ?
-
- * Slackware v3.1 : ? - ?
-
- * Slackware v3.2 : ? - ?
-
- * Slackware v3.3 : ? - 2.0.34 based
-
- * Slackware v3.4 : ? - ?
-
- * Slackware v3.5 : ? - ?
-
- * Slackware v3.6 : ? - ?
-
- * Slackware v3.9 : ? - 2.0.37pre10 based
-
- * Slackware v4.0 : YES - 2.2.6 based
-
- * Slackware v7.0 : YES - 2.2.13 based
-
- * Slackware v7.1 : YES - 2.2.16 based
-
- * Slackware v8.0 : YES - 2.4.17 based
-
- * Slackware v8.1 : YES - ? based
-
- * Stampede Linux v? : ? - ?
-
- * SuSE v5.2 : YES - 2.0.32 base
-
- * SuSE v5.3 : YES - ?
-
- * SuSE v6.0 : YES - 2.0.36 based
-
- * SuSE v6.1 : YES - 2.2.5 based
-
- * SuSE v6.3 : YES - 2.2.13 based
-
- * Tomsrbt Linux v? : ? - ?
-
- * TurboLinux Lite v4.0 : YES - ?
-
- * TurboLinux v6.0 : YES - 2.2.12 based
-
- * TriLinux v? : ? - ?
-
- * Yggdrasil Linux v? : ? - ?
-
-
-
------------------------------------------------------------------------------
-
-7.2. ( Requirements ) - What are the minimum hardware requirements and any
-limitations for IP Masquerade? How well does it perform?
-
-A 486/66 box with 16MB of RAM was more than sufficient to fill a 1.54Mb/s T1
-100%! MASQ has also been known to run quite well on 386SX-16s with 8MB of
-RAM. Yet, it should be noted that Linux IP Masquerade starts thrashing the
-system with more than 500 MASQ entries.
-
-The only application that I know which can temporarily break Linux IP
-Masquerade, is GameSpy. Why? When it refreshes its lists, it creates 10,000s
-of quick connections in a VERY short period of time. Until these sessions
-timeout, the MASQ tables become "FULL". See Section 7.23 of the FAQ for more
-details.
-
-While we are at it:
-
-There is a hard limit of 4096 concurrent connections each for TCP & UDP. This
-limit can be changed by fiddling the values in /usr/src/linux/net/ipv4/
-ip_masq.h - a maximum limit of 32000 should by OK. If you want to change the
-limit - you need to change the PORT_MASQ_BEGIN & PORT_MASQ_END values to get
-an appropriately sized range above 32K and below 64K.
------------------------------------------------------------------------------
-
-7.3. ( Errors ) - When I run the rc.firewall command, I get "command not
-found" errors. Why?
-
-How did you put the rc.firewall onto your machine? Did you cut&paste it into
-a TELNET window, FTP it from a Windows/DOS machine, etc? Try this.. log into
-your Linux box and run "vim -b /etc/rc.d/rc.firewall" and see if all your
-lines end in a ^M. If they do, delete all the ^M and try again.
------------------------------------------------------------------------------
-
-7.4. ( Still wont work ) - I've checked all my configurations, I still can't
-get IP Masquerade to work. What should I do?
-
-
-
- * Stay calm. Get yourself a cup of tea, coffee, soda, etc., and have a
- rest. Once your mind is clear, try the suggestions mentioned below.
- Setting up Linux IP Masquerading is NOT hard but there are several
- concepts that will be new to you.
-
- * Again, go through all the steps in Chapter 5. 99% of all first-time
- Masquerade users who have problems haven't looked here.
-
- * Check the IP Masquerade Mailing List Archives, most likely your questions
- or problems are a common one and can be found in a simple Archive search.
-
- * Check out the [http://www.ecst.csuchico.edu/~dranch/LINUX/
- index-linux.html#TrinityOS] TrinityOS document. It covers IP Masquerading
- for both the 2.0.x and 2.2.x kernels and MANY other topics including
- PPPd, DialD, DHCP, DNS, Sendmail, etc.
-
- * Make sure that you aren't running ROUTED or GATED. To verify, run "ps aux
- | grep -e routed -e gated"
-
- * Post your question to the IP Masquerade Mailing List (see next the FAQ
- section for details). Please only use this if you cannot find the answer
- from the IP Masquerading Archive. Be sure to include all the information
- requested in Chapter 5 in your email!!
-
- * Post your question to a related Linux NNTP newsgroup.
-
- * Send email to [mailto:ambrose@writeme.com] ambrose@writeme.com and
- [mailto:dranch@trinnet.net] dranch@trinnet.net. You have a better chance
- of getting a reply from the IP Masquerading Email list than either of us.
-
- * Check your configurations again :-)
-
-
-
------------------------------------------------------------------------------
-
-7.5. ( Email list ) - How do I join or view the IP Masquerade and/or IP
-Masqurade Developers mailing lists and archives?
-
-There are two ways to join the two Linux IP Masquerading mailing lists. The
-first way is to send an email to [mailto:masq-request@indyramp.com]
-masq-request@indyramp.com. To join the Linux IP Masquerading Developers
-mailing list, send an email to [mailto:masq-dev-request@indyramp.com]
-masq-dev-request@indyramp.com. Please see the bullet below for more details.
-
-
-
- * Subscribe via email: Now put the word "subscribe" in either the subject
- or body of the e-mail message. If you want to only subscribe to the
- Digest version of either the main MASQ or MASQ-DEV list (all e-mails on
- the given list during the week are sent to you in one big email), put the
- words "subscribe digest" in either the subject or body of the e-mail
- message.
-
- Once the server receives your request, it will subscribe you to your
- requested list and give you a PASSWORD. Save this password as you will
- need it to later unsubscribe from the list or change your options.
-
-
-
-
-The second method is to use a WWW browser and subscribe via a form at [http:/
-/home.indyramp.net/mailman/listinfo/masq] http://home.indyramp.net/mailman/
-listinfo/masq for the main MASQ list or [http://home.indyramp.net/mailman/
-listinfo/masq-dev] http://home.indyramp.net/mailman/listinfo/masq-dev for the
-MASQ-DEV list.
-
-Once subscribed, you will get emails from your subscribed list. It should be
-also noted that both subscribed and NON-subscribed users can access the two
-list's archives. To do this, please see the above two WWW URLs for more
-details.
-
-Lastly, please note that you can only post to the MASQ list from the original
-account/address you used to subscribe.
-
-If you have any problems regarding the mailing list or the mailing list
-archive, please contact Robert Novak.
------------------------------------------------------------------------------
-
-7.6. ( NAT vs. Proxy ) - How does IP Masquerade differ from Proxy or NAT
-services?
-
-Proxy: Proxy servers are available for: Win95, NT, Linux, Solaris, etc.
-
- Pro: + (1) IP address ; cheap
- + Optional caching for better performance (WWW, etc.)
-
- Con: - All applications behind the proxy server must both SUPPORT
- proxy services (SOCKS) and be CONFIGURED to use the Proxy
- server
- - Screws up WWW counters and WWW statistics
-
- A proxy server uses only (1) public IP address, like IP MASQ, and acts
- as a translator to clients on the private LAN (WWW browser, etc.).
- This proxy server receives requests like TELNET, FTP, WWW,
- etc. from the private network on one interface. It would then in turn,
- initiate these requests as if someone on the local box was making the
- requests. Once the remote Internet server sends back the requested
- information, it would re-translate the TCP/IP addresses back to the
- internal MASQ client and send traffic to the internal requesting host.
- This is why it is called a PROXY server.
-
- Note: ANY applications that you might want to use on the
- internal machines *MUST* have proxy server support
- like Netscape and some of the better TELNET and FTP
- clients. Any clients that don't support proxy servers
- won't work.
-
- Another nice thing about proxy servers is that some of them
- can also do caching (Squid for WWW). So, imagine that you have 50
- proxied hosts all loading Netscape at once. If they were installed
- with the default homepage URL, you would have 50 copies of the same
- Netscape WWW page coming over the WAN link for each respective computer.
- With a caching proxy server, only one copy would be downloaded by the
- proxy server and then the proxied machines would get the WWW page from
- the cache. Not only does this save bandwidth on the Internet
- connection, it will be MUCH MUCH faster for the internal proxied
- machines.
-
-
-
-MASQ: IP Masq is available on Linux and a few ISDN routers such
- or as the Zytel Prestige128, Cisco 770, NetGear ISDN routers, etc.
-1:Many
- NAT
- Pro: + Only (1) IP address needed (cheap)
- + Doesn't require special application support
- + Uses firewall software so your network can become
- more secure
-
- Con: - Requires a Linux box or special ISDN router
- (though other products might have this.. )
- - Incoming traffic cannot access your internal LAN
- unless the internal LAN initiates the traffic or
- specific port forwarding software is installed.
- Many NAT servers CANNOT provide this functionality.
- - Special protocols need to be uniquely handled by
- firewall redirectors, etc. Linux has full support
- for this (FTP, IRC, etc.) capabilty but many routers
- do NOT (NetGear DOES).
-
- Masq or 1:Many NAT is similar to a proxy server in the sense that the
- server will perform IP address translation and fake out the remote server
- (WWW for example) as if the MASQ server made the request instead of an
- internal machine.
-
- The major difference between a MASQ and PROXY server is that MASQ servers
- don't need any configuration changes to all the client machines. Just
- configure them to use the linux box as their default gateway and everything
- will work fine. You WILL need to install special Linux modules for things
- like RealAudio, FTP, etc. to work)!
-
- Also, many users operate IP MASQ for TELNET, FTP, etc. *AND* also setup a
- caching proxy on the same Linux box for WWW traffic for the additional
- performance.
-
-
-NAT: NAT servers are available on Windows 95/NT, Linux, Solaris, and some
- of the better ISDN routers (not Ascend)
-
- Pro: + Very configurable
- + No special application software needed
-
- Con: - Requires a subnet from your ISP (expensive)
-
- Network Address Translation is the name for a box that would have a pool of
- valid IP addresses on the Internet interface which it can use. Whenever the
- Internal network wanted to go to the Internet, it associates an available
- VALID IP address from the Internet interface to the original requesting
- PRIVATE IP address. After that, all traffic is re-written from the NAT
- public IP address to the NAT private address. Once the associated PUBLIC
- NAT address becomes idle for some pre-determined amount of time, the
- PUBLIC IP address is returned back into the public NAT pool.
-
- The major problem with NAT is, once all of the free public IP addresses are
- used, any additional private users requesting Internet service are out of
- luck until a public NAT address becomes free.
-
-For an excellent and very comprehensive description of the various forms of
-NAT, please see:
-
- * [http://www.suse.de/~mha/linux-ip-nat/diplom/nat.html] http://www.suse.de
- /~mha/linux-ip-nat/diplom/nat.html/
-
-
-
-
-Here is another good site to learn about NAT, although many of the URLs are
-old but still valid:
-
- * [http://www.linas.org/linux/load.html] http://www.linas.org/linux/
- load.html/
-
-
-
------------------------------------------------------------------------------
-
-7.7. ( GUI ) - Are there any GUI firewall creation/management tools?
-
-Yes! They vary in the type of user interface, complexity, etc. but they are
-quite good though most are only for the IPFWADM tool so far. Here is a short
-list of available tools in alphabetical order. If you know of any others or
-have any thoughts on which ones are good/bad/ugly, please email David.
-
-
-
- * John Hardin's IPFWADM Dot file generator - a IPCHAINS version is in the
- works
-
- * Sonny Parlin's [http://www.innertek.com] fBuilder: From the author of
- FWCONFIG, this new solution is fully WWW based and offers redundancy
- options, etc for both IPCHAINS and NetFilter.
-
- * William Stearns's [http://www.pobox.com/~wstearns/mason/] Mason - A
- Build-a-ruleset on-the-fly type system
-
-
-
------------------------------------------------------------------------------
-
-7.8. ( MASQ and Dynamic IPs ) - Does IP Masquerade work with dynamically
-assigned IP addresses?
-
-Yes, it works with either dynamic IP addressed assigned by your ISP via
-either PPP or a DHCP/BOOTp server. As long as you have a valid Internet IP
-address, it should work. Of course, static IP works too. Yet, if you plan on
-implementing a strong IPFWADM/IPCHAINS ruleset and/or plan on using a Port
-forwarder, your ruleset will have to be re-executed everytime your IP address
-changes. Please see the top of [http://www.ecst.csuchico.edu/~dranch/LINUX/
-index-linux.html#TrinityOS] TrinityOS - Section 10 for additional help with
-strong firewall rulesets and Dynamic IP addresses.
------------------------------------------------------------------------------
-
-7.9. ( MASQ and various networks ) - Can I use a cable modem (both
-bi-directional and with modem returns), DSL, satellite link, etc. to connect
-to the Internet and use IP Masquerade?
-
-Yes, as long as Linux supports that network interface, it should work. If you
-receive a dynamic IP address, please see the URL under the "Does IP
-Masquerade work with dynamically assigned IP" FAQ item above.
------------------------------------------------------------------------------
-
-7.10. ( Dial on Demand ) - Can I use Diald or the Dial-on-Demand feature of
-PPPd with IP MASQ?
-
-Definitely! IP Masquerading is totally transparent to Diald or PPP. The only
-thing that might become an issue is if you use STRONG firewall rulesets with
-dynamic IP addresses. See the FAQ item, "Does IP Masquerade work with
-dynamically assigned IP addresses?" above for more details.
------------------------------------------------------------------------------
-
-7.11. ( Apps ) - What applications are supported with IP Masquerade?
-
-It is very difficult to keep track of a list of "working applications".
-However, most of the normal Internet applications are supported, such as WWW
-browsing (Netscape, MSIE, etc.), FTP (such as WS_FTP), TELNET, SSH,
-RealAudio, POP3 (incoming email - Pine, Eudora, Outlook), SMTP (outgoing
-email), etc. A somewhat more complete list of MASQ-compatible clients can be
-found in Section 6.3 in this HOWTO.
-
-Applications involving more complicated protocols or special connection
-methods such as video conferencing software need special helper tools.
-
-For more details, please see the [http://www.tsmservices.com/masq/] Linux IP
-masquerading Applications page.
------------------------------------------------------------------------------
-
-7.12. ( Distro Setup ) - How can I get IP Masquerade running on Redhat,
-Debian, Slackware, etc.?
-
-No matter which Linux distribution you have, the procedures for setting up IP
-Masquerade mentioned in this HOWTO should apply. Some distributions may have
-GUI or special configuration files that make the setup easier. We tried our
-best to write this HOWTO as general as possible.
------------------------------------------------------------------------------
-
-7.13. ( Timeouts ) - Connections seem to break if I don't use them often. Why
-is that?
-
-IP Masq, by default, sets its timers for TCP session, TCP FIN, and UDP
-traffic to 15 minutes. It is recommend to use the following settings (as
-already shown in this HOWTO's /etc/rc.d/rc.firewall ruleset) for most users:
-
-Linux 2.4.x with IPTABLES
-
-+---------------------------------------------------------------------------+
-|IPMASQ timeouts are NOT adjustable under IPTABLES |
-+---------------------------------------------------------------------------+
-
-Linux 2.2.x with IPCHAINS:
-
-+---------------------------------------------------------------------------+
-|# MASQ timeouts |
-|# |
-|# 2 hrs timeout for TCP session timeouts |
-|# 10 sec timeout for traffic after the TCP/IP "FIN" packet is received |
-|# 60 sec timeout for UDP traffic (MASQ'ed ICQ users must enable a 30sec |
-|# firewall timeout in ICQ itself) |
-|# |
-|/ipchains -M -S 7200 10 60 |
-+---------------------------------------------------------------------------+
-
-Linux 2.0.x with IPFWADM:
-
-+---------------------------------------------------------------------------+
-|# MASQ timeouts |
-|# |
-|# 2 hrs timeout for TCP session timeouts |
-|# 10 sec timeout for traffic after the TCP/IP "FIN" packet is received |
-|# 60 sec timeout for UDP traffic (MASQ'ed ICQ users must enable a 30sec |
-|# firewall timeout in ICQ itself) |
-|# |
-|/sbin/ipfwadm -M -s 7200 10 60 |
-+---------------------------------------------------------------------------+
------------------------------------------------------------------------------
-
-7.14. ( Odd Behavior ) - When my Internet connection first comes up, nothing
-works. If I try again, everything then works fine. Why is this?
-
-The reason is because you have a dynamic IP address and when your Internet
-connection first comes up, IP Masquerade doesn't know its IP address. There
-is a solution to this. In your /etc/rc.d/rc.firewall ruleset, add the
-following:
-
-+-----------------------------------------------------------------------------------+
-|# Dynamic IP users: |
-|# |
-|# If you get your IP address dynamically from SLIP, PPP, or DHCP, enable this |
-|# following option. This enables dynamic-ip address hacking in IP MASQ, making |
-|# the life with Diald and similar programs much easier. |
-|# |
-|echo "1" > /proc/sys/net/ipv4/ip_dynaddr |
-+-----------------------------------------------------------------------------------+
------------------------------------------------------------------------------
-
-7.15. ( MTU ) - IP MASQ seems to be working fine but some sites don't work.
-This usually happens with WWW and some FTP sites.
-
-Depending on what Linux kernel version you are running on the MASQ server,
-some will people disagree on the real problem. The two following arguments
-have valid points, are inter-related, and users from each camp continue to
-debate this to this day.
-
- * With modern 2.4.x Linux systems, most users point their finger at the
- adminstrators of these remote broken sites (typically SSL-encrypted WWW
- sites, etc.) or your MASQ server's upstream router run by your ISP. The
- main though it that these machines are either filtering or not properly
- responding to SOME or ALL FORMS of ICMP packets (specifically ICMP Code 3
- Type 4 - Fragmentation Needed) messages due to a fray of misplaced
- security paranoia.
-
- What does that all mean? Basically, say your machine is connected to the
- Internet with a MTU of 1492 bytes (Maximum Transmission Unit -- the
- maximum packet size your computer can transmit) which is common for PPPoE
- users. At the same time, the remote WWW/FTP site is connected to the
- Internet at a MTU of 1500 bytes. The way that TCP/IP works is that when a
- TCP connection is being negotiated for your HTTP / FTP connection, the
- remote side will try to verify that a 1500 byte packet can reach your
- computer via the initial TCP "SYN" packet.
-
- Since the packet is too big for your connection, your upstream router
- (run by your ISP) will send a ICMP 3:4 (fragmentation needed) packet back
- to the remote WWW / FTP server. Within this packet is a recommended
- smaller MTU size to retry with. The problem is that either your local
- upstream router, some router between you and the remote server, or the
- remote HTTP / FTP server is either misconfigured or has a firewall in
- front of it that is BLOCKing these ICMP packets.
-
- * The final UNCOMMON possibility is a debatable 2.0 / 2.2 kernel bug in the
- IPMASQ code. Some users point their finger to the fact that IPMASQ might
- have problems with ICMP packets that have the DF or "Don't Fragment" bit
- set. Basically, when a MASQ box connects to the Internet with an MTU of
- anything less than 1500, some packets will have the DF field set. Though
- changing the MTU of the MASQ server's Internet link to 1500 seemingly
- fixes the problem, the possible bug is still there. What is believed to
- be happening in these older kernels is that the MASQ code is not properly
- re-writing the return IP addresses of the ICMP 3 Sub 4 code packets back
- to the originating MASQed computer. Because of this, these critical
- packets get dropped.
-
-
-No worries though. A there are several perfectly good ways to fix this nasty
-MTU problem:
-
- * Enable PMTU clamping in PPPoE
-
- This solution is mostly for modern 2.4.x and 2.2.x kernel users connected
- to the Internet via a PPPoE DSL or Cablemodem connections. This solution
- allows for changes to be done ONLY on the MASQ server itself and not on
- all of the internal MASQ clients.
-
- * Enable PMTU clamping via IPTABLES
-
- This solution is only modern 2.4.x kernel users connected via ANY type of
- Internet connection. This solution allows for changes to be done ONLY on
- the MASQ server itself and not on all of the internal MASQ clients.
-
- * Change your MASQ server's Internet Link MTU
-
- This solution will work for any Linux kernel version but is is NOT a
- solution if you have a PPPoE connection for DSL/Cablemodem users.
-
- It should be noted that some users will balk at this solution because it
- can hurt some latency specific programs like TELNET and Internet games
- but the impact is only slight. On the other hand, most HTTP and FTP
- traffic will SPEED UP!
-
- * Change the MTU of all internal MASQed machines
-
- This solution requires the most work as you have to make minor changes to
- ALL of the internal IPMASQed machines. Basically, you would be changing
- the MTU on all of the internal machines to match the MTU of your MASQ
- server's Internet connection. Fortunately, this solution is usually
- bulletproof where as some of the other solutions mentioned in this
- section might rarely not work.
-
-
------------------------------------------------------------------------------
-7.15.1. Enabling PMTU Clamping for PPPoE and some PPP Users:
-
-For those users who use PPPoE clients for (DSL / Cablemodem) or PPP (Dialup),
-you're Internet connection is NOT "eth0" (for example) but usually "ppp0". In
-addition to this, your Internet link's MTU or Maximum Transmission Unit
-(largest packet you can transmit over the Internet) isn't 1500 bytes but
-1492. The 1492 byte MTU comes from the link size of Ethernet (1518 bytes) -
-Ethernet MAC overhead (18) = 1500. Then you subtract the PPPoE header (8
-bytes) == MTU of 1492. This overhead isn't a big deal but sometimes ISPs or
-remote Internet sites do stupid things to break PPPoE or non-1500 byte MTU
-connected machines.
-
-You can find more info about this topic on the web. Specifically, here is
-good presentaion on the topic: mss-talk presentation (PDF). Here is the
-entire Write up and other good info
-
-To enable clamping in both the RP or PPPd PPPoE clients, add the following
-line to your /etc/ppp/pppoe.conf file:
-+----------------------------------------------------------------------------+
-| # - If you have a computer acting as a gateway for a LAN, choose "1412". |
-| # The setting of 1412 is safe for either setup, but uses slightly more |
-| # CPU power. |
-| # |
-| CLAMPMSS=1412 |
-| |
-+----------------------------------------------------------------------------+
------------------------------------------------------------------------------
-
-7.15.2. Clamping the MSS via IPTABLES:
-
-As mentioned above for PPPoE users, some ISPs and WWW sites filter critical
-ICMP packets like MTU Path Discovery. Because of this, many users might find
-mosr Internet sites work but others hang or work poorly. Fortunately, recent
-IPTABLES have added PMTU Clamping support which should help you. If your
-using IPTABLES and think you're hitting this issue, try adding the following
-line to the end of your rc.firewall-2.4 ruleset. It should be noted that
-there is no PMTU clamping support in IPCHAINS.
-+------------------------------------------------------------------------------------+
-| iptables -I FORWARD -p tcp --tcp-flags SYN,RST SYN -j TCPMSS --clamp-mss-to-pmtu |
-| |
-+------------------------------------------------------------------------------------+
-
-If this line causes an error when you re-run the rc.firewall-2.4* firewall
-rulesets, you might need to upgrade your version of IPTABLES which includes
-the "TCPMSS" IPTABLES module.
------------------------------------------------------------------------------
-
-7.15.3. Changing the External MTU of the MASQ server:
-
-This solution usually only applies to DIALUP users since PPPoE users cannot
-INCREASE their MTU because of PPPoE's header overhead.
-
-To use this solution, first see what your current MTU for your Internet link
-is. To do so, run "/bin/ifconfig" on the MASQ server. Look at the lines that
-corresponds to your Internet connection and look for the MTU (for example,
-ppp0). This NEEDs to be set to 1500. Usually, Ethernet links will default to
-1500 for Ethernet but serial / DIALUP modem PPP links might default to 576.
-
- * To change the MTU on a standard Ethernet link to your bridged or routed
- DSL, Cablemodem, etc. connection, you need to edit the correct network
- startup scripts for your Linux distribution. Please see the [http://
- www.ecst.csuchico.edu/~dranch/LINUX/index-linux.html#TrinityOS] TrinityOS
- - Section 16 document for network optimizations.
-
- * To change the MTU issue on a PPP (not PPPoE) Internet link, edit your "/
- etc/ppp/options" file and towards the top, add the following text on two
- seperate lines, add:
- +---------------------------------------------------------------+
- | mtu 1500 |
- | mru 1500 |
- | |
- +---------------------------------------------------------------+
-
- Save these new changes and then restart PPP. Like shown above, verify
- that your PPP link has the correct MTU and MTU.
-
- CUA Users: Lastly, though this isn't a common problem, some Linux 2.0.x
- kernel users have found a MTU solution to the following problem. With PPP
- users, verify what port is your PPPd code connecting to. Is it a /dev/cua
- * port or a /dev/ttyS* port? It NEEDS to be a /dev/ttyS* port as the /dev
- /cua* device ststem has been deprecated and it breaks some things in very
- odd ways.
-
-
------------------------------------------------------------------------------
-7.15.4. Changing the MTU of various operating systems:
-
-If you reconfigure ALL of your MASQed PCs to use the SAME MTU as your
-external Internet link's MTU (for example, 1492 for PPPoE users), everything
-should work fine and this method is sometimes the MOST EFFECTIVE way of
-fixing things. This is including ALL of the solutions mentioned above. But
-doing things this way can be a lot of work if there are lots of internal
-MASQed machines or be even impossible to do if you don't have administrative
-access to all the internal MASQed machines.
-
-Follow these simple steps for your respective operating system:
-
-The follow examples utilize an MTU of 1492 for typical PPPoE connections for
-some DSL and Cablemodem users. It is recommended to use the HIGHEST values
-possible for all connections that are 128Kb/s and faster. It should be noted
-that some PPPoE ISPs might require an MTU setting of 1460 (not 1492) for
-proper connectivity due to additional overhead in the ISP's internal network.
-
-The only real reason to use smaller MTUs than 1492 or 1460 is to lower your
-Internet link's latency but at the cost of throughput. Please see [http://
-www.ecst.csuchico.edu/~dranch/PPP/ppp-performance.html#mtu] http://
-www.ecst.csuchico.edu/~dranch/PPP/ppp-performance.html#mtu for more details
-on this topic.
-
-If you know how to make similar changes like these to other OSes like OS/2,
-MacOS, etc. please email [mailto:dranch@trinnet.net] David Ranch so it can be
-included in the HOWTO.
------------------------------------------------------------------------------
-
-7.15.4.1. Changing the MTU on Linux:
-
-
-------------------------------------------
-1. The setting of MTU can vary from Linux distribution to distribution.
-
- For Redhat: You need to edit the various "ifconfig" statements in
- the /sbin/ifup script
-
- For Slackware: You need to edit the various "ifconfig" statements in
- the /etc/rc.d/rc1.inet
-
-2. Here is one good, any-distribution-will-work example, edit the
- /etc/rc.d/rc.local file and put the following at the END of the file:
-
- echo "Changing the MTU of ETH0"
- /sbin/ifconfig eth0 mtu 1492
-
- Replace "eth0" with the interface name that is the machine's upstream
- connection which is connected to the Internet.
-
-3. For advanced options like "TCP Receive Windows" and such, detailed examples
- on how to edit the respective networking scripts for your specific Linux
- distro, etc., please see Chapter 16 of
- http://www.ecst.csuchico.edu/~dranch/LINUX/index-linux.html#trinityos
-------------------------------------------
-
------------------------------------------------------------------------------
-
-7.15.4.2. Changing the MTU on MS Windows 2000
-
-
-------------------------------------------
-1. Making ANY changes to the Registry is inheritantly risky but
- with a backup copy, you should be safe. Proceed at your
- OWN RISK.
-
-2. Goto Start-->Run-->RegEdit
-
-3. Registry-->Export Registry File-->Save a copy of your registry
- to a reliable place
-
-4. Navigate down to the key:
-
- [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters\Inter
-faces\
-
- Each ID Adapter has default keys for DNS, TCP/IP address, Default Gateway,
- subnet mask, etc. Find the key one that is for your network card.
-
-5. Create the following Entry:
-
- type=DWORD
- name="MTU" (Do NOT include the quotes)
- value=1492 (Decimal) (Do NOT include the text "(Decimal)")
-
-http://support.microsoft.com/support/kb/articles/Q120/6/42.asp?LN=EN-US&SD=gn&FR=0
-
-
- *** If you know how to also change the MSS, TCP Window Size, and the
- *** TTL parameters in NT 2000, please email dranch@trinnet.net as I
- *** would love to add it to the HOWTO.
-
-5. Reboot to let the changes take effect.
-------------------------------------------
-
------------------------------------------------------------------------------
-
-7.15.4.3. Changing the MTU on MS Windows NT 4.x
-
-------------------------------------------
-1. Making ANY changes to the Registry is inheritantly risky but
- with a backup copy, you should be safe. Proceed at your
- OWN RISK.
-
-2. Goto Start-->Run-->RegEdit
-
-3. Registry-->Export Registry File-->Save a copy of your registry
- to a reliable place
-
-4. Create the following keys in the Registry trees, choose two
- possible Registry trees. Multiple entries are for various
- network devices like DialUp Networking (ppp), Ethernet NICs,
- PPTP VPNs, etc.
-
- http://support.microsoft.com/support/kb/articles/Q102/9/73.asp?LN=EN-US&SD=gn&FR=0
-
-
- [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Parameters\Tcpip]
- and
- [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\\Parameters\Tcpip]
-
- Replace "" with the respective name of your uplink LAN NIC
- interface
-
- type=DWORD
- name="MTU" (Do NOT include the quotes)
- value=1492 (Decimal) (Do NOT include the text "(Decimal>")
-
- (Do NOT include the quotes)
-
-
- *** If you know how to also change the MSS, TCP Window Size, and the
- *** TTL parameters in NT 4.x, please email dranch@trinnet.net as I
- *** would love to add it to the HOWTO.
-
-5. Reboot to make the changes take effect.
-------------------------------------------
------------------------------------------------------------------------------
-
-7.15.4.4. Changing the MTU on MS Windows 98:
-
-
-------------------------------------------
-1. Making ANY changes to the Registry is inheritantly risky but
- with a backup copy, you should be safe. Proceed at your OWN RISK.
-
-2. Goto Start-->Run-->RegEdit
-
-3. You should make a backup copy of your Registry before doing anything. To
- do this, copy the "user.dat" and "system.dat" files from the \WINDOWS
- directory and put them into a safe place. It should be noted that the
- previously mentioned method of using "Regedit: Registry-->Export Registry
- File-->Save a copy of your registry" would only perform Registry MERGES
- and NOT do a replacement.
-
-4. Search though each of the Registry trees that end in "n" (e.g. 0007)
- and have a Registry entry called "IPAddress" which has the IP address
- of your NIC. Under that key, add the following:
-
- From http://support.microsoft.com/support/kb/articles/q158/4/74.asp
-
- [Hkey_Local_Machine\System\CurrentControlset\Services\Class\NetTrans\000n]
- type=STRING
- name="MaxMTU" (Do NOT include the quotes)
- value=1492 (Decimal) (Do NOT include the text "(Decimal)")
-
-
-5. You can also change the "TCP Receive Window" which sometimes
- increases network performance SUBSTANTIALLY. If you notice your
- throughput has DECREASED, put these items BACK to their original
- settings and reboot.
-
- [HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\VxD\MSTCP]
-
- type=STRING
- name="DefaultRcvWindow" (Do NOT include the quotes)
- value=32768 (Decimal) (Do NOT include the text "(Decimal>")
-
- type=STRING
- name="DefaultTTL" (Do NOT include the quotes)
- value=128 (Decimal) (Do NOT include the text "(Decimal>")
-
-
-6. Reboot to let the changes take effect.
-------------------------------------------
-
------------------------------------------------------------------------------
-
-7.15.4.5. Changing the MTU on MS Windows 95:
-
-
-------------------------------------------
-1. Making ANY changes to the Registry is inheritantly risky but
- with a backup copy, you should be safe. Proceed at your OWN RISK.
-
-2. Goto Start-->Run-->RegEdit
-
-3. You should make a backup copy of your Registry before continuing. To
- do this, copy the "user.dat" and "system.dat" files from the \WINDOWS
- directory and put them into a safe place. It should be noted that the
- previously mentioned method of using "Regedit: Registry-->Export Registry
- File-->Save a copy of your registry" would only do Registry MERGES and NOT
- do a replacement.
-
-4. Search through each of the Registry trees that end in "n" (e.g. 0007)
- and have a Registry entry called "IPAddress", which has the IP address
- of your NIC. Under that key, add the following:
-
- From http://support.microsoft.com/support/kb/articles/q158/4/74.asp
-
- [Hkey_Local_Machine\System\CurrentControlset\Services\Class\NetTrans\000n]
-
- type=DWORD
- name="MaxMTU" (Do NOT include the quotes)
- value=1492 (Decimal) (Do NOT include the text "(Decimal)")
-
- type=DWORD
- name="MaxMSS" (Do NOT include the quotes)
- value=1450 (Decimal) (Do NOT include the text "(Decimal>")
-
-
-5. You can also change the "TCP Receive Window" which sometimes
- increases network performance SUBSTANTIALLY. If you notice your
- throughput has DECREASED, put these items BACK to their original
- settings and reboot.
-
- [HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\VxD\MSTCP]
- type=DWORD
- name="DefaultRcvWindow" (Do NOT include the quotes)
- value=32768 (Decimal) (Do NOT include the text "(Decimal>")
-
- type=DWORD
- name="DefaultTTL" (Do NOT include the quotes)
- value=128 (Decimal) (Do NOT include the text "(Decimal>")
-
-
-6. Reboot to let the changes take effect.
-------------------------------------------
-
------------------------------------------------------------------------------
-
-7.16. ( FTP ) - MASQed FTP clients don't work.
-
-Check to see that the "ip_masq_ftp" module is loaded. To do this, log into
-the MASQ server and run the command "/sbin/lsmod". If you don't see the
-"ip_masq_ftp" module loaded, make sure that you followed the BASIC /etc/rc.d/
-rc.firewall recommendations found in Section 3.4. If you are implementing
-your own ruleset, make sure you include most of the examples from the HOWTO
-or you will have many susequent problems.
------------------------------------------------------------------------------
-
-7.17. ( Performance ) - IP Masquerading seems slow
-
-There might be a few reasons for this:
-
- * You might be unrealistic about how much available bandwidth is on your
- modem line. Lets do the math for a typical 56k modem connection:
-
- 1. 56k modems = 56,000 bits per second.
-
- 2. You really DON'T have a 56k modem but a 52k modem per US FCC
- limitations.
-
- 3. You'll almost NEVER get 52k, the best connection I used to get was
- 48k
-
- 4. 48,000 bits per second is 4,800 BYTES per second (8 bits to a byte +
- 2 bits for the START and STOP RS-232 serial bits)
-
- 5. With an MTU of 1500, you will get (3.2) packets in one second. Since
- this will involve fragmentation, you need to round DOWN to (3)
- packets per second.
-
- 6. Again with MTU of 1500, thats 3.2 x 40 bytes of TCP/IP overhead (8%)
-
- 7. So the BEST throughput you could hope for is 4.68KB/s w/o
- compression. Compression, be it v.42bis hardware compression, MNP5,
- or MS/Stac compression can yeild impressive numbers on highly
- compressable stuff like TEXT files, but acutally slow things down
- when transfering pre-compressed files like ZIPs, MP3s, etc.
-
-
-
-Ethernet attached setups (DSL, Cablemodem, LANs, etc)
-
- * Make sure you don't have both your INTERNAL and EXTERNAL networks running
- on the same network card with the "IP Alias" feature. If you ARE doing
- this, it can be made to work but it will be excessively slow due to high
- levels of collisions, IRQ usage, etc. It is highly recommended that you
- install another network card for the internal and external networks to
- have their own interface.
-
- * Make sure you have the right Ethernet settings for both SPEED and DUPLEX.
-
- * Some 10Mb/s Ethernet cards and most 100Mb/s cards support FULL Duplex
- connections. Direct connections from an Ethernet card to, say, a DSL
- modem (without any hubs in between) *CAN* be set to FULL DUPLEX but only
- if the DSL modem supports it. You should also be sure that you have
- Ethernet cables with all eight wires used and that they are in good
- condition.
-
- Internal networks that use HUBs -cannot- use Full Duplex. You need either
- a 10 or 100Mb.s Ethernet SWITCH to be able to do this.
-
- Both auto 10/100Mb/s SPEED negotiation and Full/Half DUPLEX negotiation
- on Ethernet cards can wreck havoc on networks. I recommend to hard code
- both the NIC speed and duplex into the NIC(s) if possible. This is
- directly possible via Linux NIC kernel modules but isn't directly
- possible in monolithic kernels. You will need to either use MII utililies
- from Section 8.1 or hardcode the kernel source.
-
-
-Optimize your MTU and set the TCP Sliding window to at least 8192
-
- * Though this is COMPLETELY out of the scope of this document, this helps
- QUITE A BIT with ANY network link you have, be it an internal or external
- PPP, Ethernet, TokenRing, etc. link. For more details, this topic is
- briefly touched in an above section in Section 7.15. For even more
- details, check out the Network Optimization section of [http://
- www.ecst.csuchico.edu/~dranch/LINUX/index-linux.html#TrinityOS] TrinityOS
- - Section 16.
-
-
-Serial based modem users with PPP
-
- * If you have an external modem, make sure you have a good serial cable.
- Also, many PCs have cheesy ribbon cables connecting the serial port from
- the motherboard or I/O card to the serial port connection. If you have
- one of these, make sure it is in good condition. Personally, I have
- ferrite coils (those grey-black metal like rings) around ALL of my ribbon
- cables.
-
- * Make sure your MTU is set to 1500 as described in the FAQ section of this
- HOWTO above
-
- * Make sure that your serial port is a 16550A or better UART. Run "dmesg |
- more" to verify
-
- * Setup IRQ-Tune for your serial ports.
-
- On most PC hardware, the use of Craig Estey's [http://cae.best.vwh.net/
- irqtune/] IRQTUNE tool and significantly increase serial port performance
- including SLIP and PPP connections.
-
- * Make sure that your serial port for your PPP connection is running at
- 115200 (or faster if both your modem and serial port can handle it..
- a.k.a ISDN terminal adapters)
-
- + 2.0.x kernels: The 2.0.x kernels are kind of an odd ball because you
- can't directly tell the kernel to clock the serial ports at 115200.
- So, in one of your startup scripts like the /etc/rc.d/rc.local or /
- etc/rc.d/rc.serial file, execute the following commands for a modem
- on COM2:
-
- + setserial /dev/ttyS1 spd_vhi
-
- + In your PPPd script, edit the actual pppd execution line to include
- the speed "38400" per the pppd man page.
-
- + 2.2.x kernels: Unlike the 2.0.x kernels, both the 2.1.x and 2.2.x
- kernels don't have this "spd_vhi" issue.
-
- So, in your PPPd script, edit the actual pppd execution line to
- include the speed "115200" per the pppd man page.
-
-
-
-All interface types:
------------------------------------------------------------------------------
-
-7.18. ( PORTFW ) - IP Masquerading with PORTFWing seems to break when my line
-is idle for long periods
-
-If you have a DSL or Cablemodem, this behavior is unfortunately quite common.
-Basically your ISP is putting your connection into a very low priority queue
-to better service non-idle connections. The problem is that some enduser's
-connections will actually be taken OFFLINE until some traffic from the user's
-DSL/Cablemodem connection awakens the ISP's hardware.
-
- * Some DSL installations can take an idle connection OFFLINE and only be
- checked for activity once every 30 seconds or so.
-
- * Some Cablemodem setups can set an idle connection into a low priority
- queue and only be checked for activity every minute or so.
-
-
-What do I recommend to do? Ping your default gateway every 30 seconds. To do
-this, edit the /etc/rc.d/rc.local file and add the following to the bottom of
-the file:
-
- ping -i 30 100.200.212.121 > /dev/null &
-
-Replace the 100.200.212.121 with your default router (upstream router).
------------------------------------------------------------------------------
-
-7.19. ( PORTFW - Locally ) - I can't reach my PORTFWed server from the
-INTERNAL lan
-
-This is a common problem which is explained in in Section 6.7 under "Note #
-2".
-
-Basically, say your domain, acme.com, has an external IP address is 1.2.3.4
-and you are PORTFWing all WWW traffic to an internal machine, say,
-192.168.1.20. Then as an /internal/ user, you are trying to contact to http:/
-/www.acme.com and expect things to work. Well, that isn't correct. Basically,
-http://www.acme.com is being resolved to the IP of http://1.2.3.4. What you
-really should doing is contacting http://192.168.1.20.
-
-See the difference?
-
-The proper solution to this is to setup a SPLIT DNS server. Internal users
-would be configured to use the /internal/ DNS server which would reply with
-the 192.168.1.20 address when asked for www.acme.com. All external users will
-get a reply from the /external/ server resolving to the the 1.2.3.4 IP
-address. From there, IPTABLES/IPCHAINS/IPFWADM would then PORTFW the traffic
-to the 192.168.1.20 server like normal.
-
-Another alternative if you only have a few internal machines is to setup a
-"hosts" file entry on all internal machines. That entry would basically look
-like:
-
-+---------------------------------------------------------------------------+
-|www.acme.com 192.168.1.20 |
-+---------------------------------------------------------------------------+
-
-Got it? If you are interested in doing the more scalable DNS approach,
-TrinityOS completely covers split and chrooted DNS servers. [http://
-www.ecst.csuchico.edu/~dranch/LINUX/index-linux.html#TrinityOS] TrinityOS -
-Section 24 http://www.ecst.csuchico.edu/~dranch/LINUX/index-linux.html#
-trinityos
-
-Now, if the split DNS server or hosts file idea doesn't interest you, you can
-add the following line to your firewall ruleset. Please note that this
-section currently doesn't cover the use of REDIR. If you need help with
-REDIR, send me an email.
-
-+---------------------------------------------------------------------------+
-|# $IPTABLES - this is the full path to where your copy |
-|# of iptables is |
-|# |
-|# $PORTFW - this is the IP address of the internal WWW |
-|# server |
-|# |
-|# $INTLAN - this is the network of your internal MASQed |
-|# network. e.g. 192.168.1.0/24 |
-|# |
-|# $INTIP - this is the internal IP address of the |
-|# MASQ server |
-| |
-|$IPTABLES -t nat -A POSTROUTING -d $PORTFW -s $INTLAN \ |
-| -p tcp --dport 80 -j SNAT --to $INTIP |
-+---------------------------------------------------------------------------+
-
-The problem with this approach is that every packet will be going from the
-MASQed web client, to the MASQ server, to the MASQed WWW server, and back
-again. This is very wasteful on both network bandwidth and server CPU!
------------------------------------------------------------------------------
-
-7.20. ( Logs ) - Now that I have IP Masquerading up, I'm getting all sorts of
-weird notices and errors in the SYSLOG log files. How do I read the IPTABLES/
-IPCHAINS/IPFWADM firewall errors?
-
-There is probably a few common things that you are going to see:
-
- * MASQ: Failed TCP Checksum error: You might see this error when a packet
- coming from the Internet gets corrupt in the data section of the packet
- but the rest of it "seems" ok. When the Linux box receives this packet,
- it will calculate the CRC of the packet and determine that its corrupt.
- On most machines running OSes like Microsoft Windows, they just silently
- drop the packets but Linux IP MASQ reports it. If you get a LOT of them
- over your PPP link, first follow the FAQ entry above for "(Performance) -
- Masq seems is slow".
-
- If the (Performance) FAQ tips don't help and you run PPP over dialup or
- PPPoE, you might try adding the line "-vj" (disabled VanJacobson header
- compression) to your /etc/ppp/options file and restart the PPPd
- connection.
-
- * Firewall hits: Because you are on the Internet with a decent firewall,
- you will be surprised with the number of users trying to penetrate your
- Linux box! So what do all these firewall logs mean?
-
- More so, if they are filling your logs, see the next FAQ entry on
- thoughts how to reduce all these log entries.
-
- * The following details are from the [http://www.ecst.csuchico.edu/~dranch/
- LINUX/index-linux.html#TrinityOS] TrinityOS - Section 10 documentation I
- also wrote:
-
- With the use of various firewall rulesets, a given ruleset can either
- DENY (silently drop) or REJECT traffic (sends back a ICMP error). If
- firewall logging is enabled, the errors will show up in the SYSLOG
- "messages" file found at:
-
- Redhat: /var/log
- Slackware: /var/adm
-
- If you take a look at one of these firewall logs, you would see something
- like:
-
- ---------------------------------------------------------------------
- IPTABLES:
- ---------
- Feb 23 07:37:01 Roadrunner kernel: IPTABLES IN=eth0 OUT=
- MAC=00:50:da:2e:e5:fb:00:03:47:73:c9:d2:08:00 SRC=12.75.147.174
- DST=100.200.0.212 LEN=44 TOS=0x00 PREC=0x00 TTL=64 ID=39034 DF PROTO=TCP
- SPT=4313 DPT=23 WINDOW=32120 RES=0x00 SYN URGP=0
-
-
- IPCHAINS:
- ---------
- Feb 23 07:37:01 Roadrunner kernel: input REJECT eth0 PROTO=6
- 12.75.147.174:1633 100.200.0.212:23 L=44 S=0x00 I=54054 F=0x0040 T=64
-
-
- IPFWADM:
- --------
- Feb 23 07:37:01 Roadrunner kernel: IP fw-in rej eth0 TCP 12.75.147.174:1633
- 100.200.0.212:23 L=44 S=0x00 I=54054 F=0x0040 T=64
-
- ---------------------------------------------------------------------
-
- There is a LOT of information in just this one line of SYSLOG. Lets break
- out this example. You should refer back to the original firewall hit as you
- read this.
-
- --------------
-
- 1. ===================================================================
-
- - This packet firewall "hit" occurred on "Feb 23 07:37:01"
-
- 2. ===================================================================
-
- - This packet was logged on the "RoadRunner" computer via the kernel
-
- 3. ===================================================================
-
- - IPTABLES: the SYSLOG prepend string is "iptables" for information purposes
-
- - IPCHAINS: the packet was stopped on the INPUT chain
-
- - IPFWADM: the packet was an IP packet
-
- 4. ===================================================================
-
- - IPTABLES: the packet came IN on interface "eth0"
-
- - IPCHAINS: the packet was REJECTED (vs. dropped or accepted)
-
- - IPFWADM: the packet was stopped on INPUT (vs. "fw-out" for OUT or
- "fw-fwd" for FORWARD)
-
- 5. ===================================================================
-
- - IPTABLES: the packet had NO output interface
-
- - IPCHAINS: the packet came in on the "eth0" interface
-
- - IPFWADM: the packet was REJECTED "rej" (vs. "deny" or "accept")
-
- 6. ===================================================================
-
- - IPTABLES: this display's the MAC address of the source and destination
- Ethetnet MAC address (only relivant for Ethernet networks)
-
- - IPCHAINS: the packet was IP protocol 6 or TCP
- * If you don't know that protocol 6 is for TCP, look at
- your /etc/protocols file to see what other protocol numbers
- are used for.
-
- - IPFWADM: the packet on the "eth0" interface
-
- 7. ===================================================================
-
- - IPTABLES: the packet's source IP address was 12.75.147.174
-
- - IPCHAINS: the packet's source IP address was 12.75.147.174
-
- - IPFWADM: the packet was a "TCP" packet
-
- 8. ===================================================================
-
- - IPTABLES: the packet's destination IP address was 100.200.0.212
-
- - IPCHAINS: the packet's source PORT was 1633
-
- - IPFWADM: the packet's source IP address was 12.75.147.174
-
- 9. ===================================================================
-
- - IPTABLES: the packet's length was 44 bytes
-
- - IPCHAINS: the packet's destination IP address was 100.200.0.212
-
- - IPFWADM: the packet's source PORT was 1633
-
- 10. ===================================================================
-
- - IPTABLES: the packet's TOS markings (type of service which basically
- means class of service) was 0x00 or zero.
-
- - IPCHAINS: the packet's destination PORT was 23 (telnet)
- * If you don't know that port 23 is for TELNETing, look at
- your /etc/services file to see what other ports are used
- for.
-
- - IPFWADM: the packet's destination IP address was 100.200.0.212
-
- 11. ===================================================================
-
- - IPTABLES: the packet's precedense markings (class of service) was
- 0x00 or zero.
-
- - IPCHAINS: the packet's length was 44 bytes
-
- - IPFWADM: the packet's destination PORT was 23 (telnet)
- * If you don't know that port 23 is for TELNETing, look at
- your /etc/services file to see what other ports are used
- for.
-
- 12. ==================================================================
-
- - IPTABLES: the packet's TTL or Time to Live was 64 or 64 router hops
- * Every router hop over the Internet will subtract (1) from
- this number. Usually, packets will start with a number of
- 255 (depends on the operating system) and if that number
- ever reaches (0), it means that realistically, the packet
- was lost in a network loop and should be deleted.
-
- - IPCHAINS: the packet's TOS markings (type of service which basically
- means class of service) was 0x00 or zero.
- * divide this by 4 to get the Type of Service (presidence)
-
- - IPFWADM: the packet was 44 bytes long
-
- 13. ==================================================================
-
- - IPTABLES: the packet had various TCP flags set such as SYN, SYN+ACK,
- etc. (shown in HEX)
-
- - IPCHAINS: the packet had various TCP flags set (shown in hex)
-
- - IPFWADM: the packet's TOS markings (type of service which basically
- means class of service) was 0x00 or zero.
-
- 14. ==================================================================
-
- - IPTABLES: the packet's "don't fragment" or DF bit was set from the
- source computer
-
- - IPCHAINS: the packet had a fragmentation offset of 40 (shown in HEX)
-
- --Don't worry if you don't understand this..
- * A value that started with "0x2..." or "0x3..." means the
- "More Fragments" bit was set so more fragmented packets
- will be coming in to complete this one BIG packet.
- * A value which started with "0x4..." or "0x5..." means that
- the "Don't Fragment" bit was set
- * Any other values are the Fragment offset (divided by 8) to
- be later used to recombine into the original LARGE packet
-
- - IPFWADM: the packet had various TCP flags set such as SYN, SYN+ACK,
- etc. (shown in HEX)
-
- 15. ==================================================================
-
- - IPTABLES: the packet was a TCP packet
-
- - IPCHAINS: the packet's TTL or Time to Live was 64 or 64 router hops
- * Every router hop over the Internet will subtract (1) from
- this number. Usually, packets will start with a number of
- 255 (depends on the operating system) and if that number
- ever reaches (0), it means that realistically, the packet
- was lost in a network loop and should be deleted.
-
- - IPFWADM: the packet had a fragmentation offset of 40 (shown in HEX)
-
- --Don't worry if you don't understand this..
- * A value that started with "0x2..." or "0x3..." means the
- "More Fragments" bit was set so more fragmented packets
- will be coming in to complete this one BIG packet.
- * A value which started with "0x4..." or "0x5..." means that
- the "Don't Fragment" bit was set
- * Any other values are the Fragment offset (divided by 8) to
- be later used to recombine into the original LARGE packet
-
- 16. ==================================================================
-
- - IPTABLES: the packet's soure PORT was 4313
-
- - IPCHAINS:
-
- - IPFWADM: the packet's TTL or Time to Live was 64 or 64 router hops
- * Every router hop over the Internet will subtract (1) from
- this number. Usually, packets will start with a number of
- 255 (depends on the operating system) and if that number
- ever reaches (0), it means that realistically, the packet
- was lost in a network loop and should be deleted.
-
- 17. ==================================================================
-
- - IPTABLES: the packet's destination PORT was 23 (telnet)
- * If you don't know that port 23 is for TELNETing, look at
- your /etc/services file to see what other ports are used
- for.
-
- - IPCHAINS:
-
- - IPFWADM:
-
- 18. ==================================================================
-
- - IPTABLES: the packet's TCP window (sliding or selective TCP ack)
- was 32120 bytes
-
- - IPCHAINS:
-
- - IPFWADM:
-
- 19. ==================================================================
-
- - IPTABLES: the packet's TCP reserved bits were 0x00 (HEX) - unused
-
- - IPCHAINS:
-
- - IPFWADM:
-
- 20. ==================================================================
-
- - IPTABLES: the packet's TCP header SYN bit was set
- * IPTABLES displays all the TCP header bits by name and not
- by a HEX dump
-
- - IPCHAINS:
-
- - IPFWADM:
-
- 21. ==================================================================
-
- - IPTABLES: the packet's TCP header URGENT bit was set - rarely used
-
- - IPCHAINS:
-
- - IPFWADM:
-
-
------------------------------------------------------------------------------
-7.21. ( Log Reduction ) - My logs are filling up with packet hits due to the
-new "stronger" rulesets. How can I fix this?
-
-So your realizing that a good firewall is catching a LOT of bad Internet
-traffic. That's a good thing but it's also filling up your logs to the point
-that you won't read them; that's bad. What to do?
-
-What you need to figure out is what traffic you DON"T want to log, explicitly
-match those packets in the firewall, and NOT log the packets when you drop
-them.
-
-For example, the TrinityOS firewall ruleset in section 10.7 (this would be a
-"strongest" ruleset in IPMASQ speak) gives some ideas: [http://
-www.ecst.csuchico.edu/~dranch/LINUX/TrinityOS/cHTML/TrinityOS-c-10.html]
-TrinityOS - Section 10.7
-
-Things I recommend to filter:
-
- * All RFC1918 address space (TCP/IP address ranges: 10.x.y.z/8,
- 172.16-31.y.z/12, and 192.168.y.x/16). You should /never/ receive these
- packets from an Internet connection. If you do, they are most likely
- spoofed packets
-
- * Windows File and Print Sharing (Samba or CIFS): ports 137, 138, 139, and
- 445. Windows machines like to talk a lot though most computers don't care
- what they're saying.
-
- * Class-D Multicast addresses (if you don't use Multicast): 224.0.0.0/4
-
- * Class-E and F "future" addresses: 240.0.0.0/5 and 248.0.0.0/5
-
-
-To a much lesser extent, you might want to filter other packets. I recommend
-that you verify that you are receiving these specific packet types before you
-filter them out.
-
- * RIP (the routing protocol): port 520
-
- * Some specific forms of ICMP packets - NOT all of them (that will break
- your machine and IPMASQ in general)
-
-
-Finally, you'll probably find that some individual TCP/IP address out on the
-Internet always seem to attack your IP. So, in addition to filtering various
-PORTS like above, you might want to also filter by specific SOURCE IP address
-too. After all, it is *YOUR* firewall.
------------------------------------------------------------------------------
-
-7.22. ( MASQ Security ) - Can I configure IP MASQ to allow Internet users to
-directly contact internal MASQed servers?
-
-Yes! With IPPORTFW, you can allow ALL or only a select few Internet hosts to
-contact ANY of your internal MASQed computers. This topic is completely
-covered in Section 6.7 in this HOWTO.
------------------------------------------------------------------------------
-
-7.23. ( Free Ports ) - I'm getting "kernel: ip_masq_new(proto=UDP): no free
-ports." in my SYSLOG files. Whats up?
-
-One of your internal MASQed machines are creating an abnormally high number
-of packets destined for the Internet. As the IP Masq server builds the MASQ
-table and forwards these packets out over the Internet, the table is quickly
-filling. Once the table is filled, it will give you this error.
-
-The only application that I have known which temporarily creates this
-situation is a gaming program called "GameSpy". Why? Gamespy builds a server
-list and then pings all of the servers in the list (1000s of game servers).
-By creating all these pings, it creates 1,000s of quick connections in a VERY
-short period of time. Until these sessions timeout via the IP MASQ timeouts,
-the MASQ tables become "FULL".
-
-So what can you do about it? Realistically, don't use programs that do things
-like this. If you do get this error in your logs, find it and stop using it.
-If you really like GameSpy, just don't refresh the server too often.
-Regardless, once you stop running this MASQ'ed program, this MASQ error will
-go away as these connections will eventually timeout in the MASQ tables.
------------------------------------------------------------------------------
-
-7.24. ( SETSOCKOPT ) - I'm getting "ipfwadm: setsockopt failed: Protocol not
-available" when I try to use IPPORTFW!
-
-If you get the error message "ipfwadm: setsockopt failed: Protocol not
-available", you AREN'T running your new kernel. Make sure that you moved the
-new kernel over, re-run LILO, and then reboot again.
-
-Please see the end of Section 6.7 for full details.
------------------------------------------------------------------------------
-
-7.25. ( SAMBA ) - Microsoft File and Print Sharing and Microsoft Domain
-clients don't work through IP Masq!
-
-To properly support Microsoft's SMB protocol, an IP Masq module would need to
-be written but there are three viable work-arounds. For more details, please
-see [http://support.microsoft.com/default.aspx?scid=kb;en-us;172227] this
-Microsoft KnowledgeBase article.
-
-The first way to work around this problem is to configure IPPORTFW from
-Section 6.7 and portfw TCP ports 137, 138, and 139 to the internal Windows
-machine's IP address. Though this solution works, it would only work for ONE
-internal machine.
-
-The second solution is to install and configure [http://www.samba.org] Samba
-on the Linux MASQ server. With Samba running, you can then map your internal
-Windows File and Print shares onto the Samba server. Then, you can mount
-these newly mounted SMB shares to all of your external clients. Configuring
-Samba is fully covered in a HOWTO found in a Linux Documentation Project and
-in the TrinityOS document as well.
-
-The third solution is to configure a VPN (virtual private network) between
-the two Windows machines or between the two networks. This can either be done
-via the PPTP or IPSEC VPN solutions. There is a Section 7.34 patch for Linux
-and also a full IPSEC implementation available for both 2.0.x and 2.2.x
-kernels. This solution would probably be the most reliable and secure method
-of all three solutions.
-
-All of these solutions are NOT covered by this HOWTO. I recommend that you
-look at the TrinityOS documentation for IPSEC help and John Hardin's PPTP
-page for more information.
-
-Also PLEASE understand that Microsoft's SMB protocol is VERY insecure.
-Because of this, running either Microsoft File and Print sharing or Windows
-Domain login traffic over the Internet without any encryption is a VERY BAD
-idea.
------------------------------------------------------------------------------
-
-7.26. ( IDENT ) - IRC won't work properly for MASQed IRC users. Why?
-
-The main possible reason is because most common Linux distribution's IDENT or
-"Identity" servers can't deal with IP Masqueraded links. No worries though,
-there are IDENTs out there that will work.
-
-Installing this software is beyond the scope of this HOWTO but each tool has
-its own documentation. Here are some of the URLs:
-
- * [http://freshmeat.net/projects/oidentd/?topic_id=150] Oident is a
- favorite IDENT server for MASQ users.
-
- * [http://freshmeat.net/projects/midentd/?topic_id=24] Mident is another
- popular IDENT server.
-
- * [http://http://home.indyramp.net/lists/masq/insecurity.net/sidentd.gz]
- Sident
-
- * [ftp://sunsite.unc.edu/pub/Linux/system/network/daemons/] Other Idents
-
-
-
-
-Please note that some Internet IRC servers still won't allow multiple
-connections from the same host even if they get Ident info and the users are
-different though. Complain to the remote sys admin. :-)
------------------------------------------------------------------------------
-
-7.27. ( IRC DCC ) - mIRC doesn't work with DCC Sends
-
-This is a configuration problem on your copy of mIRC. To fix this, first
-disconnect mIRC from the IRC server. Now in mIRC, go to File --> Setup and
-click on the "IRC servers tab". Make sure that it is set to port 6667. If you
-require other ports, see below. Next, goto File --> Setup --> Local Info and
-clear the fields for Local Host and IP Addresses. Now select the checkboxes
-for "LOCAL HOST" and "IP address" (IP address may be checked but disabled).
-Next under "Lookup Method", configure it for "normal". It will NOT work if
-"server" is selected. That's it. Try to the IRC server again.
-
-If you require IRC server ports other than 6667, (for example, 6969) you need
-to edit the /etc/rc.d/rc.firewall startup file where you load the IRC MASQ
-modules. Edit this file and the line for "modprobe ip_masq_irc" and add to
-this line "ports=6667,6969". You can add additional ports as long as they are
-separated with commas.
-
-Finally, close down any IRC clients on any MASQed machines and re-load the
-IRC MASQ module:
-
-/sbin/rmmod ip_masq_irc /etc/rc.d/rc.firewall
------------------------------------------------------------------------------
-
-7.28. ( IP Aliasing ) - Can IP Masquerade work with only ONE Ethernet network
-card?
-
-Yes and no. With the "IP Alias" kernel feature, users can setup multiple
-aliased interfaces such as eth0:1, eth0:2, etc but its is NOT recommended to
-use aliased interfaces for IP Masquerading. Why? Providing a secure firewall
-becomes very difficult with a single NIC card. In addition to this, you will
-experience an abnormal amount of errors on this link since incoming packets
-will almost simultaneously be sent out at the same time. Because of all this
-and NIC cards now costs less than $10, I highly recommend to just get a NIC
-card for each MASQed network segment.
-
-Users should also understand that IP Masquerading will only work with a
-physical interface such as eth0, eth1, etc. MASQing out an aliased interface
-such as "eth0:1, eth1:1, etc" will NOT work. In other words, the following
-WILL NOT WORK reliably:
-
- * It is rumored that you can simply use the destination IP address (the IP
- address associated with the ALIASed interface like eth0:1, etc.) IN PLACE
- of specifing the interface (eth0:1). This solution is not untested --
- please email dranch@trinnet.net if you have any positive or negative
- results
-
- * /sbin/ipchains -A forward -i eth0:1 -s 192.168.0.0/24 -j MASQ"
-
- * /sbin/ipfwadm -F -a m -W eth0:1 -S 192.168.0.0/24 -D 0.0.0.0/0
-
-
-
-
-If you are still interested in using aliased interfaces, you need to enable
-the "IP Alias" feature in the kernel. You will then need to re-compile and
-reboot. Once running the new kernel, you need to configure Linux to use the
-new interface (i.e. eth0:1, etc.). After that, you can treat it as a normal
-Ethernet interface with some restrictions like the one above.
------------------------------------------------------------------------------
-
-7.29. ( Multiple-LANs ) - I have two MASQed LANs but they cannot communicate
-with each other!
-
-Please see Section 6.5 for full details.
------------------------------------------------------------------------------
-
-7.30. ( SHAPING ) - I want to be able to limit the speed of specific types of
-traffic
-
-I receive lots of emails from people asking something like the following:
-
-+--------------------------------------------------------------------------------+
-|How can I control the internet bandwidth among the LAN PCs behind the IPMASQ |
-|server? Some times any local pc is downloading and it it will take the majority |
-|of the bandwidth and thus the other PCs get little bandwidth. |
-+--------------------------------------------------------------------------------+
-
-This topic really doesn't have anything to do with IPMASQ and everthing to do
-with Linux's built-in traffic shaping and rate-limiting abilities. You will
-find information about this on the LDP such as the [http://www.tldp.org/HOWTO
-/ADSL-Bandwidth-Management-HOWTO/index.html] ADSL Bandwidth HOWTO, the
-Advanced Rouring HOWTO, and the Bandwidth Limiting HOWTO. Please understand
-this is an advanced topic and any question you may have will be better served
-from people from those forums.
------------------------------------------------------------------------------
-
-7.31. ( ACCOUNTING ) - I need to do accounting on who is using the network
-
-Though this doesn't have much to do with IPMASQ, here are a few ideas. If you
-know of a better solution, please email the author of this HOWTO so it can be
-added to the HOWTO.
-
-
-
- * Idea #1: You could run the command:
- +---------------------------------------------------------------+
- |IPCHAINS: "ipchains -L -M" |
- | |
- |IPTABLES: "cat /proc/net/ip_conntrack" |
- | |
- |IPFWADM: |
- +---------------------------------------------------------------+
- once a second and log all of those entries. You could then write a
- program to merge this information into one large file. Again, this will
- only provide you with the remote IP address and nothing about the content
- viewed or downloaded.
-
- * Idea #2: Log every packet: You can match any specific traffic flows but
- this method will create VERY LARGE log files. Unfortunately, these log
- files aren't very readable and it doesn't tell you what was transfered
- (FTP files, etc.). Fortunately, setting up this form of accounting is
- easy.
-
- * Idea #3: Say you want to log all traffic going out onto the internet. You
- can setup a firewall rule to accept port 80 traffic with with the SYN bit
- set and log it. Now mind you, this will create smaller log files than the
- idea above but you will only know the destination IP address and NOT the
- WWW pages viewed.
-
- * Idea #4: Transparent Proxy: This method really doesn't use IPMASQ since
- it requires the installation and setup of the Squid HTTP/FTP proxy
- server. The benefit of this method is that internal users won't notice
- anything different in terms of connectivity but now the SysAdmin gets a
- LOT more information (files downloaded, etc). But, there are pros/cons to
- setting this up:
-
- Pro:
-
- + + full logging of all transferred files and issues FTP commands
-
- + + you can enable caching on the proxy server. With caching, you can
- save bandwidth since once a file is downloaded, any identical file
- requests will be served via the cache and not redownloaded via the
- Internet connection.
-
-
- Con:
-
- + - Setting up a transparent proxy is complicated as it requires kernel
- changes, setting up Squid, etc.
-
- + - Could be overkill for a small installation.
-
-
- Please see the [http://www.tldp.org/HOWTO/Adv-Routing-HOWTO/index.html]
- Advanced Routing HOWTO for more details.
-
-
-
------------------------------------------------------------------------------
-
-7.32. ( MULTIPLE IPs - DMZ segments) - I have several EXTERNAL IP addresses
-that I want to PORTFW to several internal machines. How do I do this?
-
-You DON'T do this with MASQ.
-
-MASQ is a 1:Many NAT setup which is the incorrect tool to perform what you
-are looking for. You are looking for is either Many:Many NAT solution or a
-Briding setup.
-
-NOTE: For users out there who are thinking about enabling multiple IP
-addresses on one internal NIC using "IP Alias" and then just PORTFWeding ALL
-of those ports (0-65535), and and finally use IPROUTE2 to maintain the proper
-source/destination IP pairs. This has been done SUCCESSFULLY on 2.0.x kernels
-and less successfully on 2.2.x kernels. Regardless of success, that isn't the
-proper way to do it, it's a total HACK, and it is not a supported MASQ
-configuration. Please, give IPTABLES on the 2.4.x kernels a serious look or
-to a much lesser extent, Section 7.30 IPROUTE2 look for 2.2.x kernels.
-
-Anyway, for forwarding external IP address to internal hosts, you basically
-have three possibilites:
-
- * +-----------------------------------------------------------------------------+
- |1. Route the external IPs |
- | |
- | (This does NOT involve IPMASQ at all but requires special WAN addressing |
- | and routing setup from your ISP): |
- | |
- | Internet -- Some public WAN -- Linux -- DMZ segment |
- | IP address Server PUBLIC IPs |
- | | |
- | +------ Internal net |
- | private IPs |
- +-----------------------------------------------------------------------------+
-
- * +---------------------------------------------------------------------------+
- |2. 1:1 NAT |
- | |
- | (Most easily done via IPTABLES or with IPCHAINS and IPROUTE2 but still |
- | some protocols cannot deal with NAT) |
- | |
- | Internet -- Linux -- DMZ segment |
- | Server Private IPs natted to 1:1 PUBLIC IPs |
- | | |
- | +------ Internal net |
- | private IPs |
- +---------------------------------------------------------------------------+
-
- * +--------------------------------------------------------------------------------+
- |3. Bridging: |
- | |
- | This is how most commercial firewalls do it as it's very slick. Basically, |
- | all public IPs transparently flow through the Linux server to the DMZ but |
- | via firewall inspection. |
- | |
- | Internet -- Linux -- DMZ segment |
- | Server PUBLIC IPs |
- | | |
- | +------ Internal net |
- | private IPs |
- +--------------------------------------------------------------------------------+
-
-
-Though this howto doesn't cover items #1 and #2 yet, email me and I can give
-you a hand. For item #3, this isn't IPMASQ anymore and thus I can't help you.
-Fortunately, there are a few HOWTOs out there on the topic:
-
- * [http://bridge.sourceforge.net/] http://bridge.sourceforge.net/
-
- * [http://www.tldp.org/HOWTO/Ethernet-Bridge-netfilter-HOWTO.html] http://
- www.tldp.org/HOWTO/Ethernet-Bridge-netfilter-HOWTO.html
-
-
-NOTE: If you have a bridged DSL or Cablemodem connection (not PPPoE), things
-are a little more difficult because your setup isn't routed. No worries
-though, check out the Bridge+Firewall Mini HOWTO and the [http://www.tldp.org
-/HOWTO/mini/Bridge+Firewall+DSL.html] Bridge+Firewall+DSL Mini HOWTO. These
-HOWTOs will teach you how to get your Linux box to support multiple IP
-addresses on a single interface!
------------------------------------------------------------------------------
-
-7.33. ( Netstat ) - I'm trying to use the NETSTAT command to show my
-Masqueraded connections but its not working
-
-There might be a problem with the "netstat" program in 2.0.x-based Linux
-distros. After a Linux reboot, running "netstat -M" works fine but after a
-MASQed computer runs some successful ICMP traffic like ping, traceroute,
-etc., you might see something like:
-
-masq_info.c: Internal Error `ip_masquerade unknown type'.
-
-The workaround for this is to use the "/sbin/ipfwadm -M -l" command. You will
-also notice that once the listed ICMP masquerade entries timeout, "netstat"
-works again.
------------------------------------------------------------------------------
-
-7.34. ( VPNs ) - I would like to get Microsoft PPTP (GRE tunnels) and/or
-IPSEC (Linux SWAN) tunnels running through IP MASQ
-
-This IS possible for specific modes. Specifically, all of the kernel versions
-(2.4.x, 2.2.x, and 2.0.x) support patches to allow for both ONE or MULTIPLE
-PPTP users behind a IPMASQ server to connect to the -same- PPTP server. The
-2.4.x kernels currently have a PPTP module now in the newest versions of the
-IPTABLES program and there is another version available on the IPMASQ WWW
-site. Please check out John Hardin's [http://www.impsec.org/linux/masquerade/
-ip_masq_vpn.html] PPTP Masq page for details.
------------------------------------------------------------------------------
-
-7.35. ( Games ) - I want to get the XYZ network game to work through IP MASQ
-but it won't work. Help!
-
-First, check Steve Grevemeyer's MASQ Applications page. If your solution
-isn't listed there, try patching your Linux kernel with Glenn Lamb's http://
-ipmasq.webhop.net/files20/loose-udp-2.0.36.patch.gz LooseUDP patch which is
-covered in Section 6.10 above. Also check out Dan Kegel's [http://
-www.alumni.caltech.edu/~dank/peer-nat.html] NAT Page for more information.
-
-If you are technically inclined, use the program "tcpdump" and sniff your
-network. Try to find out what protocols and port numbers your XYZ game is
-using. With this information in hand, subscribe to the [mailto://
-masq-subscribe@tiffany.indyramp.com] IP Masq email list and email your
-results for help.
------------------------------------------------------------------------------
-
-7.36. ( Stops working ) - IP MASQ works fine for a while but then it stops
-working. A reboot seems to fix this. Why?
-
-I bet you are using IPAUTOFW and/or you have it compiled into the kernel
-huh?? This is a known problem with IPAUTOFW. It is recommend to NOT even
-configure IPAUTOFW into the Linux kernel and use IPPORTFW option instead.
-This is covered with more details in Section 6.7.
------------------------------------------------------------------------------
-
-7.37. ( SMTP Relay ) - Internal MASQed computers cannot send SMTP or POP-3
-mail!
-
-Though this isn't a Masquerading issue but many users do this so it should be
-mentioned.
-
-SMTP: The issue is that you are probably using your Linux box as an SMTP
-relay server and get the following error:
-
-
-+---------------------------------------------------------------------------+
-|"error from mail server: we do not relay" |
-+---------------------------------------------------------------------------+
-Newer versions of Sendmail and other Mail Transfer Agents (MTAs) disable
-relaying by default (this is a good thing). So do the following to fix this:
-
-
-
- * Sendmail: Enable specific relaying for your internal MASQed machines by
- editing the /etc/sendmail.cw file and add the hostname and domain name of
- your internal MASQed machine. You should also check to see that the /etc/
- hosts file has the IP address and Fully Qualified Domain Name (FQDN)
- configured in it. Once this is done, you need to restart Sendmail for it
- to re-read its configuration files. This is covered in [http://
- www.ecst.csuchico.edu/~dranch/LINUX/index-linux.html#TrinityOS] TrinityOS
- - Section 25
-
-
-
-
-POP-3: Some users configure their internal MASQ'ed computer's POP-3 clients
-to connect to some external SMTP server. While this is fine, many SMTP
-servers out there will try to IDENT your connection on port 113. Most likely
-your problem stems around your default Masquerade policy being set to DENY.
-This is BAD. Set it to REJECT and re-run your rc.firewall ruleset.
------------------------------------------------------------------------------
-
-7.38. ( Source Routing ) - I need different internal MASQed networks to exit
-on different external IP addresses
-
-Say you have the following setup: You have multiple internal networks and
-also multiple external IP addresses and/or networks. What you want to do is
-have LAN #1 to only use External IP #1 but you wan LAN #2 to use External IP
-#2.
-
-Internal LAN ----------> official IP
-
-LAN #1 External IP #1 192.168.1.x --> 123.123.123.11
-
-LAN #2 External IP #2 192.168.2.x --> 123.123.123.12
-
-Basically, what we have described here is routing NOT only on the destination
-address (typical IP routing) but also routing based upon the SOURCE address
-as well. This is typically called "policy-based routing" or "source routing".
-This functionality is NOT available in 2.0.x kernels, it *IS* available for
-2.2.x kernels via the IPROUTE2 package, and it is built into the new 2.4.x
-kernels using IPTABLES.
-
-First, you have to understand that both IPFWADM and IPCHAINS get involved *
-AFTER* the routing system has decided where to send a given packet. This
-statement really ought to be stamped in big red letters on all IPFWADM/
-IPCHAINS/IPMASQ documentation. The reason for this is that users MUST first
-have their routing setup correct, then start adding IPFWADM/IPCHAINS and/or
-Masq features.
-
-Anyways, for the example case shown above, you will need to persuade the
-routing system to direct packets from 192.168.1.x via 123.123.1233.11 and
-packets from 192.168.2.x via 123.123.123.12. That is the hardest part and
-adding Masq on top of correct routing is easy.
-
-To do this fancy routing, you will use IPROUTE2. Because this functionality
-has NOTHING to do with IPMASQ, this HOWTO does not cover this topic in great
-detail. Please see Section 2.7 for complete URLs and documentation for this
-topic.
-
-The "iprule" and "iproute" commands are the same as "ip rule" and "ip route"
-commands (I prefer the former since it is easier to search for.) All the
-commands below are completely untested, if they do not work, please let David
-Ranch know about it but please contact the IPROUTE2 email list for help. This
-function has NOTHING to do with IP Masquerading.
-
-2.4.x. kernels:
-
-The following would be integrated into the END of your rc.firewall-2.4
-ruleset
-+---------------------------------------------------------------------------+
-| EXTIF="eth0" |
-| INTNET1="192.168.1.0/24" |
-| INTNET2="192.168.2.0/24" |
-| EXTIP1="123.123.123.11" |
-| EXTIP2="123.123.123.12" |
-| |
-| iptables -t nat -A POSTROUTING -o $EXTIF -s $INTNET1 -j SNAT --to $EXTIP1 |
-| iptables -t nat -A POSTROUTING -o $EXTIF -s $INTNET2 -j SNAT --to $EXTIP2 |
-| |
-+---------------------------------------------------------------------------+
-
-2.2.x. kernels:
-
-The first few commands only need to be done once at boot, say in /etc/rc.d/
-rc.local file.
-
-
-+-----------------------------------------------------------------------------+
-|# Allow internal LANs to route to each other, no masq. |
-| /sbin/iprule add from 192.168.0.0/16 to 192.168.0.0/16 table main pref 100 |
-|# All other traffic from 192.168.1.x is external, handle by table 101 |
-| /sbin/iprule add from 192.168.1.0/24 to 0/0 table 101 pref 102 |
-|# All other traffic from 192.168.2.x is external, handle by table 102 |
-| /sbin/iprule add from 192.168.2.0/24 to 0/0 table 102 pref 102 |
-| |
-|These commands need to be issued when eth0 is configured, perhaps in |
-|/etc/sysconfig/network-scripts/ifup-post (for Redhat systems). Be sure to |
-|do them by hand first to make sure they work. |
-| |
-|# Table 101 forces all assigned packets out via 123.123.123.11 |
-| /sbin/iproute add table 101 via 123.123.123.11 |
-|# Table 102 forces all assigned packets out via 123.123.123.12 |
-| /sbin/iproute add table 102 via 123.123.123.12 |
-| |
-|At this stage, you should find that packets from 192.168.1.x to the |
-|outside world are being routed via 123.123.123.11, packets from |
-|192.168.2.x are routed via 123.123.123.12. |
-| |
-|It is IMPORTANT that these IPROUTE2 rules be run /BEFORE/ the rc.firewall |
-|ruleset is run. |
-| |
-|If everything hangs together, the masq code will see packets being |
-|routed out on 123.123.123.11 and 123.123.123.12 and will use those addresses |
-|as the masq source address. |
-+-----------------------------------------------------------------------------+
-
------------------------------------------------------------------------------
-
-7.39. ( IPCHAINS rulesets on 2.4.x kernels ) - What the ipchains.o module can
-do on 2.4.x kernels
-
-Some people would like to continue using their legacy IPCHAINS rulesets on
-2.4.x-based kernelw. Unfortunately, unless you are only doing packet
-firewalling and not trying to do any NATing (MASQ), PORTFW, or other advanced
-features, you're in trouble.
-
- * If you ARE only doing IPCHAINS filtering, all you need to do is unload
- all IPTABLES modules shown from the "/sbin/lsmod" command. After that,
- load the IPCHAINS module by running "/sbin/modprobe ipchains". After
- that, load your IPCHAINS ruleset as normal.
-
- + Please note that if you compiled IPTABLES support statically into the
- kernel, you CANNOT load the "ipchains" module (it shouldn't be even
- present) as it will conflict with the IPTABLES kernel code. Your ONLY
- option in this case is to recompile your kernel but make the IPTABLES
- and IPCHAINS options as modules.
-
-
-
-So why can't you run IPCHAINS MASQ/PORTFW functionality with a 2.4.x kernel?
-Once the IPCHAINS module is loaded, you CANNOT use any IPTABLES commands or
-modules since the code conflicts. In addition to this, you cannot use any
-legacy 2.2.x IPCHAINS masq modules on a 2.4.x kernel as the kernels are so
-radically different. Plus, this really shouldn't be an issue as all of this
-functionality is available via native IPTABLES modules now. Finally, you
-cannot use the IPMASQADM tool with a 2.4.x kernel as the program both won't
-compile and ultimately the PORTFW kernel handlers aren't present anymore
-(it's now done natively by the IPTABLES code). So, considering all of these
-facts:
-
- * You cannot run any form of PORTFW on this 2.4.x machine
-
- * Protocols that require special handling like FTP, IRC, CuSeeme,
- RealAudio, etc. will no longer work
-
-
-Basically, the ipchains kernel module included with the 2.4.x kernels is
-intended for basic packet firewall compatibility and NOT any NAT(MASQ)
-functionality.
------------------------------------------------------------------------------
-
-7.40. ( IPTABLES vs. IPCHAINS vs. IPFWADM ) - Why do the 2.4.x, 2.2.x, and
-2.0.x kernels use different firewall systems?
-
-IPTABLES supports the following features that IPCHAINS and IPFWADM doesn't:
-
-
-
- * Stateful IPv4 protocol and application tracking
-
- * Stateful IPv6 protocol tracking
-
- * True 1:1 and 1:Many NAT
-
- * Built-in PORTFW functionality
-
- * See the Section 2.6 section for more details
-
-
-
-
-IPCHAINS supports the following features that IPFWADM doesn't:
-
-
-
- * "Quality of Service" (QoS support)
-
- * A TREE style chains system vs. LINEAR system like IPFWADM (Eg. this
- allows something like "if it is ppp0, jump to this chain (which contains
- its own difference set of rules)"
-
- * IPCHAINS is more flexible with configuration. For example, it has the
- "replace" command (in addition to "insert" and "add"). You can also
- negate rules (e.g. "discard any outbound packets that don't come from my
- registered IP" so that you aren't the source of spoofed attacks).
-
- * IPCHAINS can filter any IP protocol explicitly, not just TCP, UDP, ICMP
-
-
-
------------------------------------------------------------------------------
-
-7.41. ( Upgrades ) - I've just upgraded to the x.y.z kernel, why isn't IP
-Masquerade working?
-
-There are several things you should check assuming your Linux IP Masq box
-already has proper connections to the Internet and your LAN:
-
-
-
- * Make sure you have the necessary features and modules are compiled and
- loaded. See earlier sections for details.
-
- * Check /usr/src/linux/Documentation/Changes and make sure you have the
- minimal requirement for the network tools installed.
-
- * Make sure you followed all of the tests in Chapter 5 of the HOWTO.
-
- * Make sure you are using the proper firewall tool for you kernel be it
- IPTABLES, IPCHAINS, or IPFWADM.
-
- * If you are doing PORTFW functionality, make sure you use the correct tool
- for your kernel version. IPTABLES has everything built-in, IPCHAINS
- requires the use of IPMASQADM, and IPFWADM reaquires the use of IPPORTFW
- or IPAUTOFW. This is completely covered in Section 6.7.
-
- * Go through all setup and configuration again! Usually, it's just a typo
- or a simple mistake you are overlooking.
-
-
-
------------------------------------------------------------------------------
-
-7.42. ( EQL ) - I need help with EQL connections and IP Masq
-
-EQL has nothing to do with IP Masq though they are commonly teamed up on
-Linux boxes. Because of this, I recommend checking out the NEW version of
-[http://home.indyramp.com/masq/eql/eql.html] Robert Novak's EQL HOWTO for all
-your EQL needs.
------------------------------------------------------------------------------
-
-7.43. ( Wussing out ) - I can't get IP Masquerade to work! What options do I
-have for Windows Platforms?
-
-Looking to give up a free, reliable, high performance solution that works on
-minimal hardware and pay a fortune for something that needs more hardware, is
-lower performance and did I say less reliable? (IMHO. And yes, I have real
-life experience with these ;-)
-
-Okay, it's your call. If you want a Windows NAT and/or proxy solution, here
-is a decent listing. I don't prefer any one of these tools over another,
-especially since I haven't used them before.
-
- * Firesock (from the makers of Trumpet Winsock)
-
- + Does Proxy
-
- + [http://www.trumpet.com.au] http://www.trumpet.com.au
-
-
- * Iproute
-
- + DOS program designed to run on 286+ class computers
-
- + requires another box like Linux MASQ
-
- + (UNAVAILABLE) www.mischler.com/iproute/
-
-
- * Microsoft Proxy
-
- + Requires Windows NT Server
-
- + Quite expensive
-
- + [http://www.microsoft.com] http://www.microsoft.com
-
-
- * NAT32
-
- + Windows 95/98/NT compatible
-
- + [http://www.nat32.com] http://www.nat32.com
-
- + Roughly $25 for Win9x and $47 for Win9x and WinNT
-
-
- * SyGate
-
- + [http://www.sygate.com] http://www.sygate.com
-
-
- * Wingate
-
- + Does proxy
-
- + Costs roughly $30 for 2-3 IPs
-
- + [http://www.wingate.com] http://www.wingate.com
-
-
- * Winroute
-
- + Does NAT
-
- + [http://www.kerio.com/kerio.html] WinRoute
-
-
-
-Lastly, do a web search on "MS Proxy Server", "Wingate", "WinProxy", or goto
-[http://www.download.com] www.download.com. And definitely DON'T tell anyone
-that we sent you.
------------------------------------------------------------------------------
-
-7.44. ( Developers ) - I want to help with IP Masquerade development. What
-can I do?
-
-Join the Linux IP Masquerading DEVELOPERS list and ask the developers there
-what you can do to help. For more details on joining the list, check out
-Section 7.5 FAQ section.
-
-Please DON'T ask NON-IP-Masquerade development related questions there!!!!
------------------------------------------------------------------------------
-
-7.45. ( More INFO ) - Where can I find more information on IP Masquerade?
-
-You can find more information on IP Masquerade at the [http://
-ipmasq.webhop.net/] Linux IP Masquerade Resource that Ambrose Au maintains.
-
-You can also find more information at [http://www.ecst.csuchico.edu/~dranch/
-LINUX/index-linux.html] Dranch's Linux page where the TrinityOS and other
-Linux documents are kept.
-
-You may also find more information at [http://home.indyramp.net/mailman/
-listinfo/masq] The Semi-Original Linux IP Masquerading Web Site maintained by
-Indyramp Consulting, who also provides the IP Masq mailing list.
-
-Lastly, you can look for specific questions in the IP MASQ and IP MASQ DEV
-email archives or ask a specific question on these lists. Check out Section
-7.5 FAQ item for more details.
------------------------------------------------------------------------------
-
-7.46. ( Translators ) - I want to translate this HOWTO to another language,
-what should I do?
-
-Make sure the language you want to translate to is not already covered by
-someone else. But, most of the translated HOWTOs are now OLD and need to be
-updated. A list of available HOWTO translations are available at the [http://
-ipmasq.webhop.net/] Linux IP Masquerade Resource.
-
-If a copy of a current IP MASQ HOWTO isn't in your proposed language, please
-download the newest copy of the IP-MASQ HOWTO SGML code from the Linux IP
-Masquerade Resource. From there, begin your work while maintaining good SGML
-coding. For more help on SGML, check out [http://www.sgmltools.org]
-www.sgmltools.org
------------------------------------------------------------------------------
-
-7.47. ( Updates ) - This HOWTO seems out of date, are you still maintaining
-it? Can you include more information on ...? Are there any plans for making
-this better?
-
-Yes, this HOWTO is still being maintained. In the past, Ambrose was guilty of
-being too busy working on two jobs and didn't have much time to work on this,
-my apologies. As of v1.50, David Ranch revamped the document and got it
-current again.
-
-If you think of a topic that could be included in the HOWTO, please send
-email [mailto:dranch@trinnet.net] dranch@trinnet.net. It will be even better
-if you can provide that information. We will then include the information
-into the HOWTO once it is both found appropriate and tested. Many thanks for
-your contributions!
-
-We have a lot of new ideas and plans for improving the HOWTO, such as case
-studies that will cover different network setup involving IP Masquerade, more
-on security via strong IPFWADM/IPCHAINS firewall rulesets, IPCHAINS usage,
-more FAQ entries, etc. If you think you can help, please do! Thanks.
------------------------------------------------------------------------------
-
-7.48. ( Thanks ) - I got IP Masquerade working, it's great! I want to thank
-you guys, what can I do?
-
-
-
- * Can you translate the newer version of the HOWTO to another language?
-
- * Thank the developers and appreciate the time and effort they spent on
- this.
-
- * Join the IP Masquerade email list and support new MASQ users
-
- * Send an email to us and let us know how happy you are
-
- * Introduce other users to Linux and help them when they have problems.
-
-
-
-----------------------------------------------------------------------------
Chapter 8. Miscellaneous
8.1. Useful Resources
-
-
* [http://ipmasq.webhop.net/] IP Masquerade Resource page Will have all the
current information for setting up IP Masquerade on 2.0.x, 2.2.x, and
even old 1.2 kernels!
@@ -14088,8 +300,6 @@ Chapter 8. Miscellaneous
* Posting to the USENET newsgroup: [news:comp.os.linux.networking]
comp.os.linux.networking
-
-
-----------------------------------------------------------------------------
@@ -14109,1657 +319,4 @@ You may find the Linux IP Masquerade Resource at the following locations:
redirected to [http://www.e-infomax.com/ipmasq/] http://www.e-infomax.com
/ipmasq
-
-
------------------------------------------------------------------------------
-
-8.3. Thanks to the following supporters..
-
-In Alphabetical order:
-
- * Gabriel Beitler, gabrielb@voicenet.com on providing section 3.3.8
- (setting up Novell)
-
- * Juan Jose Ciarlante, irriga@impsat1.com.ar for contributing his work on
- the IPMASQADM port forward tool, the 2.1.x and 2.2.x kernel code, and the
- original LooseUDP patch, etc.
-
- * Steven Clarke, steven@monmouth.demon.co.uk for contributing his IPPORTFW
- IP port forwarder tool
-
- * Andrew Deryabin, djsf@usa.net for contributing his ICQ MASQ module
-
- * Ed Doolittle, dolittle@math.toronto.edu for suggestions to -V option in
- theipfwadm command for improved security
-
- * Matthew Driver, mdriver@cfmeu.asn.au for helping extensively on this
- HOWTO, and providing section 3.3.1 (setting up Windows 95)
-
- * Ken Eves, ken@eves.com for the FAQ that provides invaluable information
- for this HOWTO
-
- * John Hardin, jhardin@impsec.org for his PPTP and IPSEC forwarding tools
-
- * Glenn Lamb, mumford@netcom.com for the LooseUDP patch
-
- * Ed. Lott, edlott@neosoft.com for a long list of tested system and
- software
-
- * Nigel Metheringham, Nigel.Metheringham@theplanet.net for contributing his
- version of the IP Packet Filtering and IP Masquerading HOWTO, which makes
- this HOWTO a better and in-depth technical document section 4.1, 4.2, and
- others
-
- * Keith Owens, kaos@ocs.com.au for providing an excellent guide on ipfwadm
- section 4.2 on correction to ipfwadm -deny option which avoids a security
- hole, and clarified the status of ping over IP Masquerade
-
- * Michael Owings, mikey@swampgas.com for providing the section about
- CU-SeeMe and Linux IP-Masquerade Teeny How-To
-
- * Rob Pelkey, rpelkey@abacus.bates.edu for providing section 3.3.6 and
- 3.3.7 (setting up MacTCP and Open Transport)
-
- * Harish Pillay, h.pillay@ieee.org for providing section 4.5
- (dial-on-demand using Diald)
-
- * Mark Purcell, purcell@rmcs.cranfield.ac.uk for providing section 4.6
- (IPautofw)
-
- * David Ranch, dranch@trinnet.net for maintaining the HOWTO, helping with
- the Linux IP Masquerade Resource Page, the TrinityOS document, ..., too
- many to list here :-)
-
- * Paul Russell, rusty@linuxcare.com.au for all his work on IPTABLES,
- IPCHAINS, the IP Masquerade kernel patches in general, etc. The man is a
- IP NATing fool!
-
- * Ueli Rutishauser, rutish@ibm.neton providing section 3.3.9 (setting up OS
- /2 Warp)
-
- * Steve Grevemeyer, grevemes@tsmservices.com for taking over the IP Masq
- Applications page from Lee Nevo and updating it to a full DB backend.
-
- * Fred Viles, fv@episupport.com for his patches on proper port forarding of
- FTP.
-
- * John B. (Brent) Williams, forerunner@mercury.net on providing section
- 3.3.7 (setting up Open Transport)
-
- * Enrique Pessoa Xavier, enrique@labma.ufrj.bron the BOOTp setup suggestion
-
- * All the users on the IP-MASQ email list, masq@indyramp.com for their help
- and support for all the new Linux MASQ users.
-
- * Other code and documentation developers of IP Masquerade for this great
- feature
-
- * Delian Delchev, delian@wfpa.acad.bg
-
- * David DeSimone (FuzzyFox), fox@dallas.net
-
- * Jeanette Pauline Middelink, middelin@polyware.iaf.nl
-
- * Miquel van Smoorenburg, miquels@q.cistron.nl
-
- * Jos Vos, jos@xos.nl
-
- * And others who I may have failed to mention here (please let me know)
-
- * All users sending feedback and suggestions to the mailing list,
- especially those who reported errors in the document and the clients who
- are supported and not supported
-
- * We apologize if we have omitted any important names, not included
- information that some fellow users have sent us yet, etc. There were many
- suggestions and ideas sent but there wasn't enough time to verify and
- integrate these changes. David Ranch is constantly trying his best to
- incorporate all of the information sent to me into the HOWTO. I thank you
- for the effort, and I hope you understand our situation.
-
-
-
------------------------------------------------------------------------------
-
-8.4. Reference
-
-
-
- * Original IP masquerade FAQ by Ken Eves
-
- * IP masquerade mailing list archive by Indyramp Consulting
-
- * IP Masquerade WWW site by Ambrose Au
-
- * Ipfwadm page by X/OS
-
- * Various networking related Linux HOWTOs
-
- * Some topics covered in TrinityOS by David Ranch
-
-
-
------------------------------------------------------------------------------
-
-8.5. ChangeLOG
-
-TO do - HOWTO:
-
- * Add the scripted IPMASQADM example to the Forwarders section. Also
- confirm the syntax.
-
- * Add a little section on having multiple subnets behind a MASQ server
-
- * Confirm the IPCHAINS ruleset and make sure it is consistant with the
- IPFWADM ruleset
-
-
-
-
-TO DO - WWW page:
-
- * Update the PPTP patch on the masq site
-
- * Update the portfw FTP patch
-
-
-
-
-Changes from 06/22/03 to 11/09/03
-
- * 10/25/03: Fixed a dead RFC1918 URL in section 3.3. Thanks to Mark Sobell
- for the report.
-
- * 07/07/03: Added the "reducing-masq-log" FAQ entry to help people reduce
- the size of their firewall logs.
-
- * 06/27/03: Updated the rc.firewall-2.4-stronger ruleset to 0.80s. Added a
- DISABLED ip_nat_irc kernel module section, changed the default of the
- ip_conntrack_irc to NOT load by default, and added additional kernel
- module comments.
-
- * 06/27/03: Updated the rc.firewall-2.4 ruleset to 0.75. Added additional
- iptables kernel module comments.
-
- * 06/24/03: Added Debian 3.0 to the supported distro list
-
- * 06/23/03: Change the PMTU URLs to point to Phil's primary www site
-
-
-Changes from 05/26/03 to 06/22/03
-
- * 06/22/03: Updated the various Indyramp MASQ email URLs again as things
- seemed to have changed. Again.
-
- * 06/21/03: Rewrote the MTU FAQ section to be more clear, include specific
- information of the problems, and also fixed a bad typo for PPPoE users
- who were trying to configure "--clamp-mss-to-mtu" when it should have
- been "--clamp-mss-to-pmtu" (missing the p in pmtu).
-
- * 06/13/03: Added kernel info for Mandrake 8.1
-
- * 06/02/03: Fixed a typo where extended 2.2.x kernel checks for IPMASQ
- functionality was using "cat" and not "ls"
-
-
-Changes from 04/08/03 to 05/26/03
-
- * 05/26/03: updated the firewall rulesets: rc.firewall-2.4 (to 0.74),
- rc.firewall-2.2 (to 1.22), rc.firewall-2.4-stronger (to 0.79s), and
- rc.firewall-2.2-strongerw (to 0.71s) to use modprobe instead of insmod.
-
- * 05/26/03: Added how to dump IPTABLES MASQ entries in the Accounting FAQ
- section
-
- * 05/26/03: Added Clamp-MSS recommendations to the MTU faq section
-
- * 05/26/03: Added additional troubleshooting steps in Section 5 when the
- MASQ client cannot ping the MASQ server.
-
- * 05/26/03: Added additional traffic shaping / traffic limiter URLs to the
- SHAPING FAQ entry
-
- * 05/26/03: Renamed the "IPROUTE2" FAQ entry to "Souce Routing"; Added
- IPTABLES examples to the section; fixed an incorrect IP address of
- 62123.123.123.123
-
- * 05/25/03: Fixed a SGML script that was improperly converting ampersands
- for the downloadable firewall-* and rc.firewall-* scripts. Also caught a
- SGML ampersand bug in a comment section of the rc.firewall-2.0 file
-
- * 05/25/03: Deleted several dead links: ftp.gts.cz, novell.com LWP5, Old
- Juanjox mirror (geocities), old ipmasq2.webhop.net URL, old zzdmacka NAT
- information URL, old linux.org/uk/VERSION url, old netfilter.samba.org
- URLs (no longer a netfilter mirror - redirect), old Activision BattleZone
- DLL url, old iproute2 (rpms, ras.ru, donlug, dontsk, tusur, waaug, etc.)
- urls, old rlynch ipautofw mirror
-
- * 05/25/03: Updated several URLs: suse/proxy_suite/, www.indyramp.net URLs,
- several urls with " ~ " in it became ~732 for some reason, updated all of
- the jhardin URls to point from wolfnet.com to impsec.org, updated all LDP
- urls (linuxdoc.org to tldp.org), IPCHAINS patches for 2.0.x kernels,
- metalab to tldp.org, winfiles.com to download.com, Microsoft technet
- article 172227, Oidentd, mumford LooseUDP URL, 2.2.x PORT-FTP URL,
- IRQTUNE url, midentd URL
-
- * 05/25/03: Pending updates from remote webmasters: Indyramp EQL URL,
- insecurity.net sidentd
-
- * 05/25/03: Lots of little updates like:: updated the Intro section verbage
- a little to reflect BETA kernels and not OLD kernels; Updated the Forward
- section (not PORTFW) to be a little more generic; Added a link in the
- Forward to the IPMASQ email list; Updated the dates in the copyright
- notice;
-
- * 05/24/03: Updated the "Current Status" to add the remark that some
- programs have been updated to use NAT-friendly protocols and thus special
- NAT modules are no longer required
-
- * 05/24/03: Updated the 2.4 Requirements section: deleted a duplicate line
- (true 1:1 NAT); cleaned some addition things up; Added CuSeeme to the 2.4
- ported list
-
- * 05/24/03: Updated the 2.2 / 2.0 Requirements section: Deleted the
- reference to the obsoltele IPMASQ ICQ module; Updated the link for the
- LooseUDP URL;
-
- * 05/24/03: Updated the Compiling Linux 2.2.x / 2.0.x section: Deleted the
- recommendations to load the rc.firewall ruleset via rc.local. This should
- come later in the HOWTO and offer other methods for different Linux
- distributions
-
- * 05/24/03: Updated the ICQ Application section to say that these steps are
- /not/ required for modern ICQ clients. I've left this section in the
- HOWTO to demonstrate a large PORTFW example
-
- * 05/24/03: Made some of the FAQ entries more kernel version generic and
- also deleted the 2.0.x "upgrades-cont.html" FAQ entry as it was basically
- a duplicate
-
- * 05/24/03: Updated the LooseUDP game section to explain how it works,
- explain how much of this was properly solved under the stateful IPTABLES
- systtem, and also say that it is NOT available for the 2.4.x kernels. If
- IPTABLES's stateful UDP tracking doesn't work for, you're probably out of
- luck.
-
- * 05/24/03: Mentioned in the FAQ section that MASQ timers are NOT
- adjustable under IPTABLES
-
- * 05/24/03: Vastly expanded the packet firewall log FAQ entry and finally
- added a IPTABLES packet log description section. I also aligned the
- IPCHAINS example to match the IPFWADM entry
-
- * 04/11/03: Fixed a incorrect echo statement saying the IPTABLES policy was
- being set to REJECT and not DROP.
-
-
-Changes from 01/31/03 to 04/08/03
-
- * 04/08/03: Added additional formatting and the "ip_masquerade" /proc entry
- into Section 3.2. This helps users determine if their kernel is
- MASQ-ready.
-
- * 03/08/03: Added the EXTIP variable to the 2.4.x PORTFW example as several
- people were trying to use this with the BASIC ruleset and I had assumed
- they were using the STRONGER ruleset. Thanks to Greg Lukins for bringing
- this to my attention.
-
- * 03/08/03: Added Distros to the MASQ compatibility list: Mandrake, Gentoo
-
- * 02/08/03: Forgot to update the VERSION number for the
- rc.firewall-2.4-stronger rulese. Added some additional formatting
-
- * 02/01/03: Added additional checking in the kernel compiling section to
- understand if your kernel supports IPMASQ via modules or by being
- statically compiled in.
-
-
-Changes from 01/12/03 to 01/31/03
-
- * 01/31/03: Doh. I should have read my own comments. I've reversed the
- 2.4.x. policy settings from REJECT back to DROP. REJECT, for some lame
- reason, is not a legal policy. The recommended REJECT action is still
- carried out via the "drop-and-log-it" user chain.
-
- * 01/30/03: Updated the Multiple-IPs FAQ entry to better describe how users
- that want to put external IPs behind a Linux router. Added additional
- URLs and cleaned up the text a bit too.
-
- * 01/30/03: Updated the 2.4.x requirement section to reflect more of the
- pros of IPTABLES as well as updated the update status of some old legacy
- 2.2.x modules
-
- * 01/30/03: Added an additional FAQ entry that clearly explains what the
- ipchains.o module can and CANNOT do on 2.4.x. kernels
-
- * 01/28/03: Extensively updated the 2.4.x kernel compilation section to
- reflect a 2.4.20 kernel with IPTABLES 1.2.7a. The section also reflects
- the new methods to compile IPTABLES, apply Patch-O-Matic patches, and
- also included lots of example output too.
-
- * 01/28/03: Updated the kernel compiling section to be a little more clear
- on how different Linux distros can have different kernels (modules vs.
- monolithic)
-
- * 01/17/03: Fixed a major issue where the rc.firewall-2.2-stronger ruleset
- was referencing missing executable variables. This was taken from the
- 2.4-stronger ruleset but I guess I forgot to finish it off. Fixed. Thanks
- to Samuel Kim for catching this!
-
- * 01/17/03: Fixed an issue where the rc.firewall-2.2-stronger's commented
- HTTP section was missing the "-p tcp" option. Thanks to Samuel Kim for
- catching this!
-
- * 01/16/03: Updated the URL for DJSF's ICQ module
-
- * 01/16/03: Changed the default policy and drop chain from DENY to REJECT
- on both IPTABLES rulesets and on the advanced IPFWADM rulset. Thanks to
- Jonathan Hutchins for bringing this to my attention.
-
- * 01/16/03: Fixed a typo in the commented out HTTPd OUTPUT section of the
- rc.firewall-2.2-s ruleset
-
- * 01/13/03: Updated the IPMASQ www site URL from ipmasq.cjb.net to
- ipmasq.webhop.net. CJB started to change their policies so we switched.
-
- * 01/13/03: Added to the 2.4.x Requirements section that IPTABLES v1.2.7a
- is out and recommended.
-
- * 01/13/03: Added an additional test item to the "Test Section - Section 5"
- for versions of IPTABLES that are too old. I also cleaned up this section
- to read easier.
-
- * 01/13/03: Updated the rc.firewall-2.4-stronger ruleset to include
- commented rules to allow in HTTP traffic to a local HTTP server. Also
- added a rule comment in the FORWARD section to help users know where to
- put PORTFW commands.
-
- * 01/13/03: Updated the rc.firewall-2.2-stronger ruleset to include
- commented rules to allow in HTTP traffic to a local HTTP server. Also
- added a rule comment in the FORWARD section to help users know where to
- put PORTFW commands.
-
- * 01/13/03: Clarified the PORTFW section to help users better understand
- where the PORTFW commands should go in the rc.firewall rulesets. I also
- cleaned up this section to read a little better.
-
-
-Changes from 12/13/02 to 01/12/03
-
- * 01/03/03: Added Redhat 7.3 and 8.0 to the compatibility chart.
-
- * 01/03/03: Fixed various typos. Thanks to Gabriel Withington for the sharp
- eye.
-
- * 12/22/02: Updated the 2.2.x H.323 kernel patch URL. Thanks to Maxime
- Plante for pointing this out.
-
- * 12/22/02: Updated the 2.4.x kernel compiling section to let users know
- that most modern kernels don't need IPTABLES Patch-o-matic patches to be
- applied except to fix bugs or add additional functionality.
-
-
-Changes from 10/20/02 to 12/13/02
-
- * 11/27/02: Fixed the init.d scripts to point the header to the correct
- config file. This must be due to newer versions of "chkconfig" doing
- better checking. Please note that this might still be a problem for the
- rc.firewall-2.?-stronger rulesets. Thanks to Joris Van Puyenbroeck for
- the heads up.
-
- * 11/25/02: Updated all the firewall comments to reflect that PPPoE users
- need to user the "ppp0" logical interface as their external interface
- instead of the physical interface such as "eth0". Thanks to Meng Cheah
- for the nudge.
-
- * 11/13/02: Updated the URL for the Donald Becker based NIC drivers. Thanks
- to Bruce Gorgon for the heads up.
-
- * 11/01/02: Added a new FAQ section that covers redirection of local
- INTERNAL traffic to internal PORTFWed servers
-
- * 11/01/02: Updated the PORTFW section to be a little more clear.
-
-
-Changes from 04/19/02 to 10/20/02
-
- * 09/29/02: Fixed a stray incorrect IP address pointing to metalab.unc.edu
-
- * 08/29/02: Fixed a typo in the firewall-2.2 startup script which was
- starting the 2.4 firewall and not the 2.2. version. Thanks to Jean-Marc
- Vanel for catching this.
-
- * 08/25/02: Updated the rc.firewall-2.2-stronger and rc.firewall-2.2
- scripts to use shell environment variables.
-
- * 07/09/02: Updated the FTP PORTFW section to be more readible
-
- * 07/06/02: Replaced all the filewatcher.org URLs with netfilter.org URLs
-
- * 06/12/02: Changed some of the formatting to try and help newbies better
- understand that the "\" character is used as a continuation of the
- previous line.
-
- * 06/12/02: Updated the IP address of metalab.unc.edu in Section 5. Thanks
- to Pete Trachy for bringing this to my attention but please note that
- even major sites like Metalab change their IPs, subnets, or even ISPs
- from time to time.
-
- * 06/02/02: Updated the rc.firewall-2.4 ruleset to include a commented
- option for NATing IRC DCCs, added the use of more environment vars, and
- added additional formatting.
-
- * 05/18/02: Added some extra # lines the commented section of the the
- rc.firewall-2.4-stronger ruleset to better serve Cut and Paste users.
-
- * 05/04/02: - Updated the various PPTP MASQ links to point to a valid URL.
- Also updated the HOWTO to reflect that PPTP is now supported on the 2.4.x
- kernels.
-
- * 05/03/02: - Updated the 2.4.x kernel requirements section to point out
- that IPCHAINS compatibility under 2.4.x kernels isn't very good. If you
- want to use IPMASQ under a 2.4.x kernel, you should use IPTABLES rules
- only.
-
-
-Changes from 01/05/02 to 04/19/02 - v2.00.041902 pubsished to the LDP
-
- * 04/01/02: - Updated the rc.firewall-2.4-stronger ruleset to denote and
- disable internal DHCP server support on the OUTPUT rules
-
- * 02/09/02: - Added Redhat-style init.d scripts to start the rc.firewall
- files
-
- * 02/09/02: - Updated all the various chapters to use human readable file
- names vs. things like x2623.html.
-
- * 02/09/02: - Expanded the IPMASQ accounting section
-
- * 02/04/02: - Deleted an extra "$" from the PORTFW variable in section
- 6.7.1
-
- * 01/31/02: - Updated the URLs for the PPPd and Diald homepages
-
- * 01/26/02: - Fixed some typos and added a LooseUDP clarification to tell
- users to read the example rc.firewall-2.2 ruleset comments on how to
- enable LooseUDP.
-
- * 01/08/02: - Made some slight clarifications to IP Alias support
-
-
-Changes from 11/19/01 to 01/05/02 - 010502 pubsished to the LDP
-
- * 01/05/02: - Added disabled rules to the rc.firewall-2.4-stronger ruleset
- to support INTERNAL DHCP server and EXTERNAL access to a WWW server
- running on the MASQ machine.
-
- * 01/05/02: - Added required changes to the loading of the ip_conntrack_ftp
- module if people PORTFW to non-standard FTP ports.
-
- * 01/05/02: - Added an example in the 2.4.x PORTFW section on how to
- REDIRECT internal traffic back to an INTERNAL server. This is the same as
- running REDIR under 2.2.x and 2.0.x kernels.
-
- * 01/05/02: - Added Juanjox mirror URLs to the HOWTO.
-
- * 01/04/02: - Clarified and cleaned up the ICQ PORTFW section; Added
- thoughts on the ip_masq_icq, PORTFW, and SOCKS solutions
-
- * 01/05/02: - Added Slackware 8.0 to the supported list.
-
- * 01/04/02: - Fixed some spelling mistakes in the 2.4 and 2.2 rulesets.
- Thanks to Michael Ott for the sharp eye.
-
- * 12/19/01: - Fixed a minor comment typo in the rc.firewall-2.4 file.
- Thanks to Bruno Negrao for this one.
-
- * 12/02/01: - Fixed some minor version typos in the 2.4.x rc.firewall
- ruleset; Added a missing $PORTFWIF variable for the 2.4.x PORTFW example.
- Thanks to Neil Bunn for the errata.
-
- * 11/25/01: - Expanded on the ipchains module conflict error messages in
- Section 5
-
- * 11/23/01: - Updated the HOWTO to reflect a new PPTP kernel module for the
- 2.4.x kernels
-
- * 11/19/01: - Clarified the PPTP supports for 2.4.x kernels
-
-
-Changes from 08/26/01 to 11/18/01 - 111801 published to the LDP
-
- * 11/12/01: - updated various comments to reflect new versions:linux
- 2.4.14, iptables 1.2.4, and linux 2.2.20.
-
- * 11/12/01: - Added the rc.firewall-2.4-stronger ruleset to the HOWTO,
- updated the 2.4.x kernel and IPTABLES compiling steps to reflect 2.4.14
- and 1.2.4.
-
- * 11/10/01: - Added the directly downloadable versions of the 2.4,
- 2.4-stronger, 2.2, 2.2-stronger, 2.0, and and 2.0.x-stronger rulesets to
- the WWW.
-
- * 11/10/01: - Updated the 2.4.x PORTW example to add the missing FORWARD
- option.
-
- * 11/10/01: - Updated the DSL-HOWTO link in the HOWTO
-
- * 10/27/01: - Updated the network diagram in section 2.5 to be a little
- more verbose.
-
- * 09/18/01: - Fixed some broken reference links pointing to the respective
- 2.4.x, 2.2.x, and 2.0.x kernel compiling recommendations.
-
- * 09/16/01: - Cleaned up and updated the PORTFW section to also include
- PREROUTING examples for 2.4.x kernels.
-
- * 09/13/01: - Updated the IPTABLES simple rc.firewall ruleset to 0.62. This
- fixed a typo on the MASQ enable line that used eth0 instead of $EXTIF.
- Thanks to Hafi for reporting this.
-
- * 09/07/01: - It seems that most people who are getting IPCHAINS and
- IPTABLES conflicts are running Redhat 7.1. I have updated section 5 on
- how to fix this. Thanks to Jason Wenzel for helping me with this.
-
- * 09/07/01: - Noted that IPTABLES v1.2.3 is current version. All versions
- less than v1.2.3 have an FTP module bug that can bypass strong firewall
- rulesets. Please upgrade your copy of IPTABLES now.
-
- * 09/07/01: - Created version numbers for the simple rc.firewall rulesets
- (IPTABLES - v0.61) (IPCHAINS - v1.01) (IPFWADM - v2.01). and cleaned up
- some of the comments in each section.
-
- * 09/07/01: - Added rules to the simple rc.firewall rulesets to flush the
- various tables. In addition to this, I have added the use of environment
- variables and more echo statements in the rulesets to make things easier
- to edit and monitor. Thanks to Ian Bishop for the good idea.
-
- * 09/07/01: - Added the use of EXTIF and INTIF interface variables in each
- of the rc.firewall and partial firewall rulesets for better clarity
- (similar to how TrinityOS has been doing for a while now). Thanks to Sean
- McKeon for the nudge.
-
- * 09/07/01: - Fixed a typo in the UNIX client configuration section where
- the network broadcast was 192.168.0.25 instead of .255.
-
-
-
-
-Changes from 2.01 to 2.05 - 08/26/01
-
- * 08/19/01: - Added an additional testing step in Section5 to make sure the
- rc.firewall file loads ok. Thanks to Steven Levis for the good idea.
-
- * 08/15/01: - Change the reference for the /etc/hosts file from RFC952 to
- RFC1035. Thanks to Michael F. Maggard for the correction.
-
-
-
-
-Changes from 1.96 to 2.01 - 08/12/01
-
- * 08/12/01: - Updated the basic IPTABLES ruleset to 0.60 which fixed a
- major issue where all MASQed packets were being dropped. Ultimately, I
- forgot to add a rule to ACCEPT correct packets through the forwarding
- chain.
-
- * - Added an additional rule to log all bogus FORWARD packets
-
- * - Load the FTP nat modules now by default
-
- * - Changed the load order of some of the kernel modules to not create
- bogus error messages
-
- * - Added an IPTABLES section on how to MASQ specific hosts vs. an entire
- subnet
-
- * - Added more MASQ-client compatible operating systems
-
-
- * 07/19/01: - The advanced IPCHAINS example for forwarding between multiple
- interfaces was missing the critital "-j ACCEPT" to actually let the
- packets flow. Thanks to Shingo Yamaguchi for catching this.
-
-
-Changes from 1.96 to 2.00 - 06/10/01
-
- * 06/21/01: Updated Section 5 (Testing Section) to add an additional test
- to help users troubleshoot their MASQ setup. There are now a total of
- -11- tests. 06/16/01: Updated the intro History section at the beginning
- of the HOWTO. 06/14/01: Added mirror Netfilter and IPCHAINs mirror URLs
- 06/13/01: Updated the H.323 URL
-
- * 06/10/01: Double DOH! The simple rc.firewall script for the 2.4 kernels
- had two major errors in it. The new version is far more informative and
- even works! I am continuing to go through the HOWTO and cleaning things
- up but I'm not done quite yet.
-
- * 06/02/01: Updated the lists of known compatible MASQ'ed operating systems
- (Windows M3, Linux 2.3, 2.4, etc) Made more references to DHCP and DNS in
- the various different MASQ client configuration guides.
-
- * 04/12/01: Thanks to the Joshua X and the other people at Command Prompt,
- Inc. for the port of the HOWTO from LinuxDoc to DocBook. Add email list
- URL to line 126
-
-
-Changes from 1.90 to 1.95 - 11/11/00
-
- * A BIG thanks to the Joshua X and the other people at Command Prompt, Inc.
- for the port of the HOWTO from LinuxDoc to DocBook.
-
- * Added a quick upfront notice in the intro that running a SINGLE NIC in
- MASQ mutliple ethernet segments is NOT recommended and linked to the
- relivant FAQ entry. Thanks to Daniel Chudnov for helping the HOWTO be
- more clear.
-
- * Added a pointer in the Intro section to the FAQ section for users looking
- for how MASQ is different from NAT and Proxy services.
-
- * Reordered the Kernel requirements sections to be 2.2.x, 2.4.x, 2.0.x
-
- * Expanded the kernel testing in Section 3 to see if a given kernel already
- supports MASQ or not.
-
- * Reversed the order of the displayed simple MASQ ruleset examples (2.2.x
- and 2.0.x)
-
- * Cleaned up some formatting issues in the 2.0.x and 2.2.x rc.firewall
- files
-
- * Noted in the 2.2.x rc.firewall that the defrag option is gone in some
- distro's proc (Debian, TurboLinux, etc)
-
- * Added a NOTE #3 to the rc.firewall scripts to include instructions for
- Pump. Thanks to Ross Johnson for this one.
-
- * Cleaned up the simple MASQ ruleset examples for both the 2.2.x and 2.2.x
- kernels
-
- * Updated the simple and stronger IPCHAINS and IPFWADM rulesets to include
- the external interface names (IPCHAINS is -i; IPFWADM is -W) to avoid
- some internal traffic MASQing issues.
-
- * Vastly expanded the Section 5 (testing) with even more testing steps with
- added complete examples of what the output of the testing commands should
- look like.
-
- * Moved the H.323 application documentation from NOT supported to
- Supported. :-)
-
- * Reordered the Multiple LAN section examples (2.2.x then 2.0.x)
-
- * Made some additional clarifications to the Multiple LAN examples
-
- * Fixed a critical typo with multiple NIC MASQing where the network
- examples had the specified networks reversed. Thanks to Matt Goheen for
- catching this.
-
- * Added a little intro to MFW in the PORTFW section.
-
- * Reveresed the 2.0.x and 2.2.x sections for PORTFW
-
- * Updated the news regarding PORTFWing FTP traffic for 2.2.x kernels
- NOTE: At this time, there *IS* a BETA level IP_MASQ_FTP module
- for PORT Forwarding FTP connections 2.2.x kernels which also supports
- adding additional PORTFW FTP ports on the fly without the requirement
- of unloading and reloading the IP_MASQ_FTP module and thus breaking
- any existing FTP transfers.
-
-
- * Added a top level note about PORTFWed FTP support
-
- * Added a noted to the 2.0.x PORTFW'ed FTP example why users DON'T need to
- PORTFW port 20.
-
- * Updated the PORTFW section to also mention that users can use FTP proxy
- applications like the one from SuSe to support PORTFWed FTP-like
- functionality. Thanks to Stephen Graham for this one.
-
- * Updated the example for how to enable PORTFWed FTP to also include
- required configurations on how the ip_masq_ftp module is loaded for users
- who use multiple PORTs to contact multiple internal FTP servers. Thanks
- to Bob Britton for reminding me about this one.
-
- * Added a FAQ entry for users who have embedded ^Ms in their rc.firewall
- file
-
- * Expanded the FAQ entry talking about how MASQ is different from NAT and
- Proxy to include some informative URLs.
-
- * Updated the explanation of the MASQ MTU issue and described the two main
- explanations for the issue.
-
- * Clarified that the RFC, PPPoE should only require an MTU of 1492 though
- some ISPs require a setting of 1460. Because of this, I have updated the
- example to show an MTU of 1492.
-
- * Broke out the Windows 9x sections into Win95 and Win98 as they use
- different settings (DWORD vs. STRING). I also updated the sections to be
- clearer and the Registry backup methods have been updated.
-
- * Fixed a typo where the NT 4.0 Registry entries were backwards (Tcpip/
- Parameters vs. Parameters/Tcpip).
-
- * Fixed an issue where the WinNT entry should have been a DWORD and not a
- STRING.
-
- * A serious thanks goes out to Geoff Mottram for his various PPPoE and
- various Windows Registry entry fixes.
-
- * Added an explict URL for Oident in the IRC FAQ entry
-
- * Updated the FAQ section regarding some broken "netstat" versions
-
- * Added new FAQ sections for MASQ accounting ideas and traffic shaping
-
- * Expanded the IPROUTE2 FAQ entry on what Policy-routing is.
-
- * Moved the IPROUTE2 URLs to the 2.2.x Kernel requirements section and also
- added a few more URLs as well.
-
- * Corrected the "intnet" varible in the stronger IPCHAINS ruleset to
- reflect the 192.168.0.0 network to be consistent with the rest of the
- example. Thanks to Ross Johnson for this one.
-
- * Added a new FAQ section for users asking about forwarding problems
- between multiple internal MASQed LANs.
-
- * Added a new FAQ section about users wanting to PORTFW all ports from
- multiple external IP addresses to internal ones. I also touched on users
- who were trying to PORTFW all ports on multiple IP ALIASed interfaces and
- also noted the Bridge+Firewall HOWTO for DSL and Cablemodem users who
- have multiple IPs in a non-routed environment.
-
- * Added Mandrake 7.1, Mandrake 7.2, and Slackware 7.1 to the supported list
-
- * Added Redhat 7.0 to the MASQ supported distros. Thanks to Eugene
- Goldstein for this one.
-
- * Fixed a mathematical error in the "Maximum Throughput" calculation in the
- FAQ section. Thanks to Joe White @ ip255@msn.com for this one.
-
- * Fixed the Windows9x MTU changes to be a STRING change and not a DWORD
- change to the registry. Thanks to jmoore@sober.com for this one.
-
- * Updated the comments in the 2.0.x rc.firewall script to note that the
- ip_defrag option is for both 2.0 and 2.2 kernels. Thanks to
- pumilia@est.it for this clarification.
-
-
-
-
-Changes from 1.85 to 1.90 - 07/03/00
-
- * Updated the URL for TrinityOS to reflect its newest layout
-
- * Caught a typo in the IPCHAINS rulesets where I was setting
- "ip_ip_always_defrag" instead of "ip_always_defrag"
-
- * The URL to Taro Fukunaga was invaild since it was using "mail:" instead
- of "mailto:"
-
- * Added some clarification to the "Masqing multiple internal interfaces"
- where some users didn't understand why eth0 was referenced multiple
- times.
-
- * Fixed another "space after the EXTIP variable" bug in the stronger
- IPCHAINS section. I guess I missed one.
-
- * In Test #7 of Section 5, I referred users to go back to step #4. That
- should have been step #6.
-
- * Updated the kernel versions that came with SuSe 5.2 and 6.0
-
- * Fixed a typo (or vs. of) in Section 7.2
-
- * Added Item #9 to the Testing MASQ section to refer users who are still
- haing MASQ problems to read the MTU entry in the FAQ
-
- * Improved the itemization in Section 5
-
- * Updated the IPCHAINS syntax to show the MASQ/FORWARD table. Before, it
- was valid to run "ipchains -F -L" but now only "ipchains -M -L" works.
-
- * Updated the LooseUDP documentation to reflect the new LooseUDP behavior
- in 2.2.16+ kernels. Before, it was always enabled, now, it defaults to
- OFF due to a possible MASQed UDP port scanning vulnerability. I updated
- the BASIC and SEMI-STRONG IPCHAINS rulesets to reflect this option.
-
- * Updated the recommended 2.2.x kernel to be 2.2.16+ since there is a TCP
- root exploit vulnerability on all lesser versions.
-
- * Added Redhat 6.2 to the MASQ supported list
-
- * Updated the link for Sonny Parlin's FWCONFIG to point to fBuilder.
-
- * Updated the various examples of IP addresses from 111.222.333.444 to be
- 111.222.121.212 and within a valid IP address range
-
- * Updated the URL for the BETA H.323 MASQ module
-
- * Finally updated the MTU FAQ section to help out PPPoE DSL and Cablemodem
- users. Basically, Section 7.15 now reflects the fact that users can also
- change the MTU settings of all of their INTERNAL machines to solve the
- dreaded MASQ MTU issue.
-
- * Added a clarification to the PORTFW section that PORTFWed connections
- which work for EXTERNAL clients but will not work for INTERNAL clients.
- If you also need INTERNAL portfw, you will need to also implement the
- REDIR tool as well. I also noted that this issue is fixed in the 2.4.x
- kernels with Netfilter.
-
- * I also added a technical explanation from Juanjo to the end of the PORTFW
- section to why this senario doesn't work properly.
-
- * Updated all of the IPCHAINS URLs to point to Paul Rusty's new site at
- http://www.netfilter.org/ipchains/
-
- * Updated Paul Rustys email address
-
- * Added a new FAQ section for users whose connections remain idle for a
- long period of time and PORTFWed connections no longer work.
-
- * Updated all the URLs to the LDP that pointed to metalab.unc.edu to the
- new site of linuxdoc.org
-
- * Updated the Netfilter URLs to point to renamed HOWTOs, etc.
-
- * I also updated the status of the 2.4.x support to note that I *will* add
- full Netfilter support to this HOWTO and if the time comes, then split
- that support off into a different HOWTO.
-
- * Updated the 2.4.x Requirements section to reflect how NetFilter has
- changed compared to IPFWADM and IPCHAINS and gave a PROs/CONs list of new
- features and changes to old behaviors.
-
- * Added a TCP/IP math example to the "My MASQ connection is slow" FAQ entry
- to better explain what a user should expect performance wise.
-
- * Updated the HOWTO to reflect that newer versions of the "pump" DHCP
- client now can run scripts upon bringup, lease renew, etc.
-
- * Updated the PORTFWing of FTP to reflect that several users say they can
- successfully forward FTP traffic to internal machines without the need of
- a special ip_masq_ftp module. I have made the HOWTO reflect that users
- should try it without the modified module first and then move to the
- patch if required.
-
-
-
-
-Changes from 1.82 to 1.85 - 05/29/00
-
- * Ambrose Au's name has been taken off the title page as David Ranch has
- been the primary maintainer for the HOWTO for over a year. Ambrose will
- still be involved with the WWW site though.
-
- * Deleted a stray SPACE in section 6.4
-
- * Re-ordered the compatible MASQ'ed OS section and added instructions for
- setting up a AS/400 system running on OS/400. Thanks to jaco@libero.it
- for the notes.
-
- * Added an additional PORFW-FTP patch URL for FTP access if HTTP access
- fails.
-
- * Updated the kernel versions for Redhat 5.1 & 6.1 in the FAQ
-
- * Added FloppyFW to the list of MASQ-enabled Linux distros
-
- * Fixed an issue in the Stronger IPFWADM rule set where there were spaces
- between "ppp_ip" and the "=".
-
- * In the kernel compiling section for 2.2.x kernels, I removed the
- reference to enable "CONFIG_IP_ALWAYS_DEFRAG". This option was removed
- from the compiling section and enabled by default with MASQ enabled in
- 2.2.12.
-
- * Because of the above change in the kernel behavior, I added the enabling
- of ip_always_defrag to all the rc.firewall examples.
-
- * Updated the status of support for H.323. There are now ALPHA versions of
- modules to support H.323 on both 2.0.x and 2.2.x kernels.
-
- * Added Debian v2.2 to the supported MASQ distributions list
-
- * Fixed a long standing issue where the section that covered explict
- filtering of IP addresses for IPCHAINS had old IPFWADM syntax. I've also
- cleaned this section up a little and made it understandable.
-
- * Doh! Added Juan Ciarlante's URL to the important MASQ resources section.
- Man.. you guys need to make me more honest than this!!
-
- * Updated the HOWTO to reflect kernels 2.0.38 and 2.2.15
-
- * Reversed the order shown to compile kernels to show 2.2.x kernels first
- as 2.0.x is getting pretty old.
-
- * Updated the 2.2.x kernel compiling section to reflect the changed options
- for the latter 2.2.x kernels.
-
- * Added a a possible solution for users that fail to get past MASQ test #5.
-
-
-
-
-Changes from 1.81 to 1.82 - 01/22/00
-
- * Added a missing subsection for /proc/sys/net/ipv4/ip_dynaddr in the
- stronger IPCHAINS ruleset. Section 6.5
-
- * Changed the IP Masq support for Debian 2.1 to YES
-
- * Reorganized and updated the "Masq is slow" FAQ section to include fixing
- Ethernet speed and duplex issues.
-
- * Added a link to Donald Becker's MII utilities for Ethernet NIC cards
-
- * Added a missing ")" for the 2.2.x section (previously fixed it only for
- the 2.0.x version) to the ICQ portfw script and changed the evaluation
- from -lt to -le
-
- * Added Caldera eServer v2.3 to the MASQ supported list
-
- * Added Mandrake 6.0, 6.1, 7.0 to the MASQ supported list
-
- * Added Slackware v7.0 to the MASQ supported list
-
- * Added Redhat 6.1 to the MASQ supported list
-
- * Added TurboLinux 4.0 Lite to the MASQ supported list
-
- * Added SuSe 6.3 to the MASQ supported list
-
- * Updated the recommended stable 2.2.x kernel to be anything newer than
- 2.2.11
-
- * In section 3.3, the HOWTO forgot how to tell the user how to load the /
- etc/rc.d/rc.firewall upon each reboot. This has now been covered for
- Redhat (and Redhat-based distros) and Slackware.
-
- * Added clarification in the Windows WFWG v3.x and NT setup sections why
- users should NOT configure the DHCP, WINS, and Forwarding options.
-
- * Added a FAQ section on how to fix FTP problems with MASQed machines.
-
- * Fixed a typo in the Stronger firewall rulesets. The "extip" variabl
- cannot have the SPACE between the variable name and the "=" sign. Thanks
- to johnh@mdscomp.com for the sharp eye.
-
- * Updated the compatibly section: Mandrake 7.0 is based on 2.2.14 and
- TurboLinux v6.0 runs 2.2.12
-
-
-
-
-Changes from 1.80 to 1.81 - 01/09/00
-
- * Updated the ICQ section to reflect that the new ICQ Masq module supports
- file transfer and real-time chat. The 2.0.x module still has those
- limitations.
-
- * Updated Steven E. Grevemeyer's email address. He is the maintainer of the
- IP Masq Applications page.
-
- * Fixed a few lines that were missing the work AREN'T for the "setsockopt"
- errors.
-
- * Updated a error the strong IPCHAINS ruleset where it was using the
- variable name "ppp_ip" instead of "extip".
-
- * Fixed a "." vs a "?" typo in section 3.3.1 in the DHCP comment section.
-
- * Added a missing ")" to the ICQ portfw script and changed the evaluation
- from -lt to -le
-
- * Updated the Quake Module syntax to NOT use the "ports=" verbage
-
-
-
-
-Changes from 1.79 to 1.80 - 12/26/99
-
- * Fixed a space typo when setting the "ppp_ip" address.
-
- * Fixed a typo in the simple IPCHAINS ruleset. "deny" to "DENY"
-
- * Updated the URLs for Bjorn's "modutils" for Linux
-
- * Added verbage about NetFilter and IPTables and gave URLs until it is
- added to this HOWTO or a different HOWTO.
-
- * Updated the simple /etc/rc.d/rc.firewall examples to notify users about
- the old Quake module bug.
-
- * Updated the STRONG IPFWADM /etc/rc.d/rc.firewall to clarify users about
- dynamic IP addresses (PPP & DHCP), newer DHCPCD syntax, and the old Quake
- module bug.
-
- * Updated the STRONG IPCHAINS /etc/rc.d/rc.firewall to ADD a missing
- section on dynamic IP addresses (PPP & DHCP) and the old Quake module
- bug.
-
- * Added a note in the "Applications that DO NOT work" section that there IS
- a beta module for Microsoft NetMeeting (H.323 based) v2.x on 2.0.x
- kernels. There is NO versions available for Netmeeting 3.x and/or 2.2.x
- kernels as of yet.
-
-
-
-
-Changes from 1.78 to 1.79 - 10/21/99
-
- * Updated the HOWTO name to reflect that it isn't a MINI anymore!
-
-
-
-
-Changes from 1.77 to 1.78 - 8/24/99
-
- * Fixed a typo in "Section 6.6 - Multiple Internal Networks" where the -a
- policy was ommited.
-
- * Deleted the 2.2.x kernel configure option "Drop source routed frames"
- since it is now enabled by default and the kernel compile option was
- removed.
-
- * Updated the 2.2.x and all other IPCHAINS sections to notify users of the
- IPCHAINS fragmentation bug.
-
- * Updated all of the URLs pointing at Lee Nevo's old IP Masq Applications
- page to Seg's new page.
-
-
-
-
-Changes from 1.76 to 1.77 - 7/26/99
-
- * Fixed a typo in the Port fowarding section that used "ipmasqadm ipportfw
- -C" instead of "ipmasqadm portfw -f"
-
-
-
-
-Changes from 1.75 to 1.76 - 7/19/99
-
- * Updated the "ipfwadm: setsockopt failed: Protocol not available" message
- in the FAQ to be clearer instead of making the user hunt for the answer
- in the Forwarders section.
-
- * Fixed incorrect syntax in section 6.7 for IPMASQADM and "portfw"
-
-
-
-
-Changes from 1.72 to 1.75 - 6/19/99
-
- * Fixed the quake module port setup order for the weak IPFWADM & IPCHAINS
- ruleset and the strong IPFWADM ruleset as well.
-
- * Added a user report about port forwarding ICQ 4000 directly in and using
- ICQ's default settings WITHOUT enabling the "Non-Sock" proxy setup.
-
- * Updated the URLs for the IPMASQADM tool
-
- * Added references to Taro Fukunaga, tarozax@earthlink.net for his MkLinux
- port of the HOWTO
-
- * Updated the blurb about Sonny Parlin's FWCONFIG tool to note new IPCHAINS
- support
-
- * Noted that Fred Vile's patch for portfw'ed FTP access is ONLY available
- for the 2.0.x kernels
-
- * Updated the 2.2.x kernel step with a few clarifications on the
- Experiemental tag
-
- * Added Glen Lamb's name to the credits for the LooseUDP patch
-
- * Added a clarification on installing the LooseUDP patch that it should use
- "cat" for non-compressed patches.
-
- * Fixed a typo in the IPAUTO FAQ section
-
- * I had the DHCP client port numbers reversed for the IPFWADM and IPCHAINS
- rulesets. The order I had was if your Linux server was a DHCP SERVER.
-
- * Added explict /sbin path to all weak and strong ruleset examples.
-
- * Made some clarifications in the strong IPFWADM section regarding Dynamic
- IP addresses for PPP and DHCP users. I also noted that the strong
- rulesets should be re-run when PPP comes up or when a DHCP lease is
- renewed.
-
- * Added references in the 2.2.x requirements, updated the ICQ FAQ section,
- and added Andrew Deryabin to the credits section for his ICQ MASQ module.
-
- * Added some clarifcations to the FAQ section explaining why the 2.1.x and
- 2.2.x kernels went to IPCHAINS.
-
- * Added a little FAQ section on Microsoft File/Print/Domain services
- (Samba) through a MASQ server. I also added an URL to a Microsoft
- Knowledge based document for more details.
-
- * Added clarifications to the FAQ section that NO Debian distribution
- supports IP masq out of the box.
-
- * Updated the supported MASQ distributions in the FAQ section.
-
- * Added to the Aliased NIC section of the FAQ that you CANNOT masq out of
- an aliased interface.
-
- * Wow.. never caught this before but the "ppp-ip" variable in the strong
- ruleset section is an invalid variable name! It has been renamed to
- "ppp_ip"
-
- * In both the IPFWADM and IPCHAINS simple ruleset setup areas, I had a
- commented out section on enabling DHCP traffic. Problem is, it was below
- the final reject line! Doh! I moved both up a section.
-
- * In the simple IPCHAINS setup, the #d out line for DHCP users, I was using
- the IPFWADM "-W" command instead of IPCHAINS's "-i" parameter.
-
- * Added a little blurb to the Forwarders section the resolution to the
- famous "ipfwadm: setsockopt failed: Protocol not available" error. This
- also includes a little /proc test to let users confirm if IPPORTFW is
- enabled in the kernel. I also added this error to a FAQ section for
- simple searching.
-
- * Added a Strong IPCHAINS ruleset to the HOWTO
-
- * Added a FAQ section explaining the "kernel: ip_masq_new(proto=UDP): no
- free ports." error.
-
- * Added an example of scripting IPMASQADM PORTFW rules
-
- * Updated a few of the Linux Documentation Project (LDP) URLs
-
- * Added Quake III support in the module loading sections of all the
- rc.firewall rulesets.
-
- * Fixed the IPMASQADM forwards for ICQ
-
- * 1.72 - 4/14/99 - Dranch: Added a large list of Windows NAT/Proxy
- alternatives with rough pricing and URLs to the FAQ.
-
- * 1.71 - 4/13/99 - Dranch: Added IPCHAINS setups for multiple internal
- MASQed networks. Changed the ICQ setup to use ICQ's default 60 second
- timeout and changed IPFWADM/IPCHAINS timeout to 160 seconds. Updated the
- MASQ and MASQ-DEV email list and archive subscription instructions.
-
- * 1.70 - 3/30/99 - Dranch: Added two new FAQ sections that cover SMTP/POP-3
- timeout problems and how to masquerade multiple internal networks out
- onto different external IP addresses with IPROUTE2.
-
- * 1.65 - 3/29/99 - Dranch: Typo fixes, clarifications of required 2.2.x
- kernel options, added dynamic PPP IP address support to the strong
- firewall section, additional quake II module ports, noted that the
- LooseUDP patch is built into later 2.2.x kernels and its from Glenn Lamb
- and not Dan Kegel, added more game info in the compatibility section.
-
- * 1.62 - Dranch: Make the final first-draft changes to the doc and now
- announce it in the MASQ email list.
-
- * 1.61 - Dranch: Made editorial changes, cleaned things up and fixed some
- errors in the Windows95 and NT setups.
-
- * 1.58 - Dranch: Addition of the port forwarding sections; LooseUDP setup;
- Ident servers for IRC users, how to read firewall logs, deleted the
- CuSeeme Mini-HOWTO since it is rarely used.
-
- * 1.55 - Dranch: Complete overhaul, feature and FAQ addition, and editing
- sweep of the v1.50 HOWTO. Completed the 2.2.x kernel and IPCHAINS
- configurations. Did a conversion from IPAUTOFW to IPPORTFW for the
- examples that applied. Added many URLs to various other documentation and
- utility sites. There are so many changes.. I hope everyone likes it.
- Final publishing of this new rev of the HOWTO to the LDP project won't
- happen until the doc is looked over and approved by the IP MASQ email
- list (then v2.00).
-
- * 1.50 - Ambrose: A serious update to the HOWTO and the initial addition of
- the 2.2.0 and IPCHAINS configurations.
-
- * 1.20 - Ambrose: One of the more recent HOWTO versions that solely dealt
- with < 2.0.x kernels and IPFWADM.
-
-
- IPMasquerading+Napster mini-HOWTO
- John E. Danner
- v1.6, 11 April 2000
-
- This mini-HOWTO present a way to allow users behind an IPMasq'd system
- to use Napster.
-
- For information about Napster, please see their website at Napster
- Homepage
-
- 1. DISCLAIMER
-
- In order to allow Napster to work correctly, you will need to put a
- hole in the IP Masq'd system. This inherently presents potential
- security problems. Unfortunately I cannot accept responsibility for
- this hack. So if you do this, and you get burned because of it...not
- my fault. Great...now lets get into it...
-
- 2. INTRODUCTION
-
- After setting up a network for my roommates and I, the problem arose
- that were not able to use Napster because of the IPMasquerading I was
- doing. So I put some time into and came up with this solution to the
- problem. I hope it works for you like it did for me...but I can't
- promise anything.
-
- 3. BEFORE YOU BEGIN
-
- I have tested this solution with the following variables:
-
-
- 1. Napster v2.0 Beta 5a (for Windows), visit Napster Homepage
- to ensure you have the newest version.
-
- 2. One external IP to the internet.
-
- 3. Currently 6 systems behind the IPMasq'd machine, 4 using Napster.
-
- 4. Using Linux kernel version 2.2.12-20 (RedHat v6.1 Distribution)
-
- 5. IPMASQADM utility version 0.42, get it Here
-
-
- 4. PROCEDURE
-
- First off, ensure that you have the version (or newer) as listed above
- in the previous section. Also be sure they are installed correctly.
-
-
- 1. Install Napster on the Windows client PC's
-
- 2. After installation and Napster user setup, this version of Napster
- will begin "Finding Acceptable Local Data Port", after a short time
- an error will occur. Note: If you have already installed napster
- v2.0 beta 5a, under the file menu select 'Properties.'
-
- 3. At this point select the second option "I am not behind a firewall
- or I configured my firewall - Use TCP port:"
-
- 4. Enter a unique number. Each computer that will be running Napster
- will need to use a different port. It may be easier to use the last
- number of the IP address. For example: if the computer's IP is
- 192.168.1.2, then 6702 would be easiest to remember. Note: make
- sure you don't pick ports for services that are running (i.e. 21,
- 110, etc...see /etc/services for a listing)
-
- 5. Repeats steps 1 - 4 for all systems that will be using Napster.
-
- 6. Now login to your IPMasq'd system and modify a startup file of your
- choice (I choose to use /etc/rc.d/rc.local)
-
- The following lines pass the connection to the Napster clients running on the hosts behind your IPMasq'd system.
- (add them to the startup file - you'll need to one command for each host using Napster)
-
- /usr/sbin/ipmasqadm portfw -a -P tcp -L xxx.xxx.xxx.xxx 6702 -R 192.168.1.2 6702
- /usr/sbin/ipmasqadm portfw -a -P tcp -L xxx.xxx.xxx.xxx 6703 -R 192.168.1.3 6703
- /usr/sbin/ipmasqadm portfw -a -P tcp -L xxx.xxx.xxx.xxx 6704 -R 192.168.1.4 6704
- /usr/sbin/ipmasqadm portfw -a -P tcp -L xxx.xxx.xxx.xxx 6705 -R 192.168.1.5 6705
-
- Note: XXX.XXX.XXX.XXX is the IP address of the Linux IPMasqing system (the Internet IP).
-
-
- Note: If you are having problems with IPMASQADM or IPMasquerading in
- general see the IPMASQ-HOWTO. This document is provided to help people
- who have their systems configured. The IPMASQ-HOWTO will get into a
- deeper discussion of port forwarding and IPMasq'd in general.
-
-
- 5. DYNAMIC IP AREA (Dial-up or DHCP)
-
- See this and the Procedure section if your IP address changes
- everytime you connect to the internet.
-
- Thanks to Peter Illmayer for the following submission to me: (This
- will work out best for those of you with dynamic IP's...)
-
- ------------------------------------------------------------
- IN debian, I created a forward file in /etc/ppp/ip-up.d and put in
-
- #!/bin/sh
- ppp_ip="`/sbin/ifconfig ppp0 | grep 'inet addr' | awk '{print $2}' | sed -e
- /usr/sbin/ipmasqadm portfw -f
- /usr/sbin/ipmasqadm portfw -a -P tcp -L ${ppp_ip} 6702 -R 192.168.0.2 6702
-
- This is in a 2.2.x kernel with ipmasqadm installed with the appropriate
- kernel modules compiled in.
- ---------------------------------------------------------------
-
-
- Charles J. Fisher pointed out that a similar script can be used if you
- are using DHCP, insert the following lines in a script that runs after
- you get your IP address.
-
- net_ip="`ifconfig eth0 | awk '/inet/ {sub(/addr:/,"",$2); print $2}'`"
- /usr/sbin/ipmasqadm portfw -f
- /usr/sbin/ipmasqadm portfw -a -P tcp -L ${net_ip} 6702 -R 192.168.1.2 6702
-
-
- Of course the more machines using Napster behind your IPMasq'd machine
- the more port forwards you need to do.
-
- 6. FINISHED PRODUCT
-
- This system will allow Napster to operate properly behind an IPMasq'd
- system. Hopefully it works for you as well as it does for me! Please
- direct comments/suggestions/flames to jed204@psu.edu
-
- 7. HOWTO MAINTENANCE
-
- This is the initial version of this document. Very rough. If the
- interest is out there and things changes, so will this document. If
- anyone else has a solution they think is better...please, all means,
- let me know and we can discuss what the best solution possible is.
-
- 8. Copyright and License
-
- Copyright (c) 2000 by John E. Danner
-
- Please freely copy and distribute (sell or give away) this document in
- any format. It's requested that corrections and/or comments be
- fowarded to the document maintainer. You may create a derivative work
- and distribute it provided that you:
-
- 1.Send your derivative work (in the most suitable format such as sgml)
- to the LDP (Linux Documentation Project) or the like for posting on
- the Internet. If not the LDP, then let the LDP know where it is
- available.
-
- 2.License the derivative work with this same license or use GPL.
- Include a copyright notice and at least a pointer to the license used.
-
- 3.Give due credit to previous authors and major contributors.
-
- If you're considering making a derived work other than a translation,
- it's requested that you discuss your plans with the current
- maintainer.
-
-Using Term to Pierce an Internet Firewall mini-HOWTO
-
-Barak Pearlmutter
-
-bap@cs.unm.edu
-
-David C. Merrill
-
-david -AT- lupercalia.net
-
-Copyright © 1996 by Barak Pearlmutter
-
-Copyright © 2001 by David C. Merrill
-Revision History
-Revision 1.1 2001-07-14 Revised by: dcm
-Cleaned up a bit, reorganized a bit, converted to DocBook SGML and relicensed
-under GFDL.
-Revision 1.0 1996-07-15 Revised by: pb
-Initial Release.
-
-
-This document explains how to use the term program to pierce a firewall from
-the inside, even without root privileges.
-
-Term is an old program that almost no one uses anymore, because the 7-bit
-serial lines it is meant to cross are nowhere to be found anymore, and full
-IP ppp access is dirt cheap.
-
-Important Archived Document Notice: This document has been archived by the
- LDP because it does not apply to modern Linux systems. It is no
- longer being actively maintained.
-
------------------------------------------------------------------------------
-Table of Contents
-1. Preface
- 1.1. Disclaimer
- 1.2. License
-
-
-2. Introduction
-3. The Basic Procedure
-4. Detailed Directions
-5. Multiple Term Sockets
-6. The ?/.term/termrc.telnet Init File
-7. Direction
-8. Security
-9. Telnet Mode
-10. Bugs and Term Wish List
-11. Tricks That Do Not Seem to Work
-12. Related Resources
-13. Acknowledgments
-
------------------------------------------------------------------------------
-1. Preface
-
-1.1. Disclaimer
-
-While every precaution has been taken in the preparation of this document,
-the Linux Documentation Project and the author(s) assume no responsibility
-for errors or omissions, or for damages resulting from the use of the
-information contained herein.
------------------------------------------------------------------------------
-
-1.2. License
-
-This document is made available under the terms of the GNU Free Documentation
-License (GFDL), which is hereby incorporated by reference.
------------------------------------------------------------------------------
-
-2. Introduction
-
-The term program is usually used to provide host-to-host services over a
-modem or serial line. However, sometimes it is useful to establish a term
-connection between two machines that communicate via telnet. The most
-interesting example is connecting two hosts which are separated by ethernet
-firewalls or SOCKS servers. Such firewalls provide facilities for
-establishing a telnet connection through the firewall, typically by using the
-SOCKS protocol, to allow inside machines to get connections out, and
-requiring outside users to telnet first to a gateway machine which requires a
-one-time password. These firewalls make it impossible to, for instance, have
-X clients on an inside machine communicate with an X server on an outside
-machine. But, by setting up a term connection, these restrictions can all be
-bypassed quite conveniently, at the user level.
------------------------------------------------------------------------------
-
-3. The Basic Procedure
-
-Setting up a term connection over a telnet substrate is a two-phase process.
-First your usual telnet client is used to set up a telnet connection and log
-in. Next, the telnet client is paused and control of the established telnet
-connection is given to term.
------------------------------------------------------------------------------
-
-4. Detailed Directions
-
-First, from a machine inside the firewall, telnet to a target machine outside
-the firewall and log in.
-
-Unless you are under linux and will be using the proc filesystem (see below)
-make sure your shell is an sh style shell. Ie if your default shell is a csh
-variant, invoke telnet by:
-
-+---------------------------------------------------------------------------+
-|setenv SHELL /bin/sh; telnet machine.outside |
-+---------------------------------------------------------------------------+
-
-After logging in, on the remote (outside) machine invoke the command:
-
-+---------------------------------------------------------------------------+
-|term -r -n off telnet |
-+---------------------------------------------------------------------------+
-
-Now break back to the telnet prompt on the local (inside) machine, using ^]
-or whatever, and use the telnet shell escape command ! to invoke term:
-
-+---------------------------------------------------------------------------+
-|telnet> ! term -n on telnet >&3 <&3 |
-+---------------------------------------------------------------------------+
-
-That's it!
-
-If you have a variant telnet, you might have to use some other file
-descriptor than 3; easy to check using strace. But three seems to work on all
-bsd descendent telnet clients I've tried, under both SunOS 4.x and the usual
-linux distributions.
-
-Some telnet clients do not have the ! shell escape command. Eg the telnet
-client distributed with Slackware 3.0 is one such client. The sources that
-the Slackware telnet client is supposedly built from
-
-ftp://ftp.cdrom.com:/pub/linux/slackware-3.0/source/n/tcpip/
-NetKit-B-0.05.tar.gz
-
-A simple solution is therefore to obtain these sources and recompile them.
-This unfortunately is a task I have had no luck with. Plus, if you are
-running from inside a SOCKS firewall, you will need a SOCKSified telnet
-client anyway. To that end, I was able to compile a SOCKSified telnet client
-from:
-
-ftp://ftp.nec.com/pub/security/socks.cstc/socks.cstc.4.2.tar.gz
-
-or, if you're outside the USA,
-
-ftp://ftp.nec.com/pub/security/socks.cstc/export.socks.cstc.4.2.tar.gz
-
-Alternatively, under linux kernels up to 1.2.13, you can pause the telnet
-with ^]^z, figure out its pid, and invoke:
-
-+---------------------------------------------------------------------------+
-|term -n on -v /proc/&,t;telnetpid>/fd/3 telnet |
-+---------------------------------------------------------------------------+
-
-This doesn't work with kernels after 1.3.x, which closed some mysterious
-security hole by preventing access to these fd's by processes other than the
-owner process and its children.
------------------------------------------------------------------------------
-
-5. Multiple Term Sockets
-
-It is a good idea to give the term socket an explicit name. This is the
-telnet; argument in the invocations of term above. Unless you have the
-TERMSERVER environment variable set to telnet as appropriate, you invoke term
-clients with the -t switch, e.g., trsh -t telnet.
------------------------------------------------------------------------------
-
-6. The ?/.term/termrc.telnet Init File
-
-I have checked line clarity using linecheck over this medium. I expected it
-to be completely transparent, but it is not. However, the only bad character
-seems to be 255. The ??/.term/termrc.telnet I use (the .telnet is the name of
-the term connection, see above) contains:
-
-+---------------------------------------------------------------------------+
-|baudrate off |
-|escape 255 |
-|ignore 255 |
-|timeout 600 |
-+---------------------------------------------------------------------------+
-
-Perhaps it could be improved by diddling, I am getting a throughput of only
-about 30k cps over a long-haul connection through a slow firewall. Ftp can
-move about 100k cps over the same route. A realistic baudrate might avoid
-some timeouts.
------------------------------------------------------------------------------
-
-7. Direction
-
-Obviously, if you are starting from outside the firewall and zitching in
-using a SecureID card or something, you will want to reverse the roles of the
-remote vs local servers given above. (If you don't understand what this
-means, perhaps you are not familiar enough with term to use the trick
-described in this file responsibly.)
------------------------------------------------------------------------------
-
-8. Security
-
-This is not much more of a vulnerability than the current possibility of
-having a telnet connection hijacked on an unsecured outside machine. The
-primary additional risk comes from people being able to use the term socket
-you set up without you even being aware of it. So be careful out there.
-(Personally, I do this with an outside machine I know to be pretty secure,
-namely a linux laptop I maintain myself that does not accept any incoming
-connections.)
-
-Another possibility is to add
-
-+---------------------------------------------------------------------------+
-|socket off |
-+---------------------------------------------------------------------------+
-
-to the remote ??/.term/termrc.telnet file, or
-
-+---------------------------------------------------------------------------+
-|add "-u off" |
-+---------------------------------------------------------------------------+
-
-to the invocation of term. This prevents the socket from being hijacked from
-the remote end, with only a minor loss of functionality.
------------------------------------------------------------------------------
-
-9. Telnet Mode
-
-Be sure the remote telnetd is not in some nasty seven-bit mode. Or if it is,
-you have to tell term about it when you invoke term, by adding the -a switch
-at both ends. (I sometimes use >^] telnet> set outbin or set bin, or invoke
-telnet with a -8 switch to put the connection into eight-bit mode.)
------------------------------------------------------------------------------
-
-10. Bugs and Term Wish List
-
-The linecheck program has some problems checking telnet connections
-sometimes. This is sometimes because it doesn't check the return code of the
-read() call it makes. For network connections, this call to read() can return
--1 with an EINTR (interrupted) or EAGAIN (try again) error code. Obviously
-this should be checked for.
-
-There are a number of features that could ease the use of term over telnet.
-These primarily relate to an assumption that influenced the design of term,
-namely that the connection is low bandwidth, low latency, and somewhat noisy.
-
-A telnet connection is in general high bandwidth, high latency, and error
-free. This means that the connection could be better utilized if (a) the
-maximum window size was raised, well above the limit imposed by term's
-N_PACKETS/2=16, (b) there was an option to turn off sending and checking
-packet checksums, and (c) larger packets were permitted when appropriate.
-
-Also, to enhance security, it would be nice to have a term option to log all
-connections through the socket it monitors to a log file, or to stderr, or
-both. This would allow one to see if one's term connection is being subverted
-by nasty hackers on the outside insecure machine.
------------------------------------------------------------------------------
-
-11. Tricks That Do Not Seem to Work
-
-Some telnet clients and servers agree to encrypt their communications, to
-prevent eavesdropping on the connection. Unfortunately, the hack used above
-(using the network connection that the telnet client has set up while the
-telnet client is idle) won't work in that case. Instead, one really must go
-through the telnet client itself, so it can do its encryption. It seems like
-that requires a simple hack to the telnet client itself, to add a command
-that runs a process with its stdin and stdout are connected to the live
-telnet connection. This would also be useful for various bots, so perhaps
-someone has already hacked it up.
------------------------------------------------------------------------------
-
-12. Related Resources
-
-A vaguely related trick is to SOCKSify one's Term library. Details, including
-patches to SOCKS, are available from Steven Danz danz@wv.mentorg.com.
------------------------------------------------------------------------------
-
-13. Acknowledgments
-
-Thanks for valuable suggestions from:
-
- * Gary Flake flake@scr.siemens.com
-
- * Bill Riemers bcr@physics.purdue.edu
-
- * Greg Louis glouis@dynamicro.on.ca
-
diff --git a/LDP/guide/docbook/Linux-Networking/IPX.xml b/LDP/guide/docbook/Linux-Networking/IPX.xml
index 23dc4df3..a3b5a283 100644
--- a/LDP/guide/docbook/Linux-Networking/IPX.xml
+++ b/LDP/guide/docbook/Linux-Networking/IPX.xml
@@ -48,1943 +48,6 @@ in the packet. Typical frame types used in NetWare networks
IPX networks through an IP only link
- This document aims to describe how to obtain, install and configure
- various tools available for the the Linux operating system that use
- the Linux kernel IPX protocol support.
-
- 1.2. Introduction.
-
- The Linux Kernel has a completely new network implementation as
- compared to other Unix like operating systems. The ability to take a
- fresh approach to developing the kernel networking software has led to
- the Linux kernel having support for a range of non tcp/ip protocols
- being built. The IPX protocol is one of those that have been included.
-
- The Linux kernel supports the IPX protocol only. It does not yet
- support protocols such as IPX/RIP, SAP or NCP, these are supported by
- other software such as that documented elsewhere in this document.
-
- The IPX support was originally developed by Alan Cox
- and has been significantly enhanced by Greg
- Page .
-
- 3.3. Mailing list support.
-
- There is a mailing list established for discussion of the various
- Linux IPX software packages described in this document. You can
- subscribe to it by sending a mail message to `listserv@sh.cvut.cz'
- with `add linware' in the body of the message. To post to the list
- your send your mail to `linware@sh.cvut.cz'. I regularly watch this
- list.
-
- The mailing list is archived at www.kin.vslib.cz
- .
-
- 5. A brief discussion of IPX network topology
-
- This is a much simplified explanation for people new to IPX. Large
- networks will probably break lots of the rules explained here. In
- complex IPX networks the administrator should always be consulted.
-
- IPX networking revolves around a scheme of numbered networks unlike IP
- which places more emphasis on the interface addresses. A network is a
- collection of equipment connected to the same LAN segment and using
- the same frame type. Different frame types on the same LAN segment are
- treated as seperate networks.
-
- Each network must be allocated a number which is unique across the
- entire internetwork. This is usually performed by a NetWare(tm)
- server, but can easily be performed by Linux. IPX clients are given
- this number by the server when starting, they only require to know the
- correct frame type.
-
- Routing between networks is usually performed by putting two network
- cards in a server. This server then runs the RIP protocol which holds
- a routing table for the internetwork. Periodic broadcasts of this
- routing table are exchanged between servers. Within a short time each
- server 'discovers' the topology of the internetwork.
-
- If you only wish to use the services of an existing NetWare server,
- you can use ipx_configure (section 7.1) to automatically define the
- IPX interfaces by using broadcast queries to look for a server. If
- this fails, or you wish to provide IPX services, you will need to
- define the interfaces manually using ipx_interface or mars_nwe.
-
-
- 6. The IPX related files in the /proc filesystem.
-
- There are a number of files related to the Linux IPX support that are
- located within the /proc filesystem. They are:
-
-
- /proc/net/ipx_interface
- This file contains information about the IPX interfaces
- configured on your machine. These may have been configured
- manually by command or automatically detected and configured.
-
- /proc/net/ipx_route
- This file contains a list of the routes that exist in the IPX
- routing table. These routes may have been added manually by
- command or automatically by an IPX routing daemon.
-
- /proc/net/ipx
- This file is a list of the IPX sockets that are currently open
- for use on the machine.
-
-
- 7. Greg Pages IPX tools.
-
- Greg Page .
-
-
- 7.1. The IPX tools in more detail.
-
-
- ipx_interface
- This command is used to manually add, delete or check ipx
- capability to an existing network device. Normally the network
- device would be an Ethernet device such at eth0. At least one
- IPX interface must be designated the primary interface and the
- -p flag to this command does this. For example to enable
- Ethernet device eth0 for IPX capability as the primary IPX
- interface using the IEEE 802.2 frame type and IPX network
- address 39ab0222 you would use:
-
-
- # ipx_interface add -p eth0 802.2 0x39ab0222
-
-
-
- If the frame type differs from NetWare(tm) servers on this network,
- they will studiously ignore you. If the frame type is correct but
- the network number differs, they will still ignore you but complain
- frequently on the NetWare server console. The latter is guaranteed
- to gain you flames from your NetWare administrator and may disrupt
- existing NetWare clients.
-
- If you get an error while running this program and you happen to
- not have already configured tcp/ip, then you will find that you
- need to manually start the eth0 interface using the command:
-
-
- # ifconfig eth0 up
-
-
-
- ipx_configure
- This command enables or disables the automatic setting of the
- interface configuration and primary interface settings.
-
- --auto_interface
- allows you to select whether new network devices should be
- automatically configured as IPX devices or not.
-
- --auto_primary
- allows you to select whether the IPX software should
- automatically select a primary interface or not. Problems
- have been noted using this with Windows 95 clients on the
- network.
-
- A typical example would be to enable both automatic interface
- configuration and automatic primary interface setting with the
- following command:
-
-
-
- # ipx_configure --auto_interface=on --auto_primary=on
-
-
-
- ipx_internal_net
- This command allows you to configure or deconfigure an internal
- network address. An internal network address is optional, but
- when it is configured it will always be the primary interface.
- To configure an IPX network address of ab000000 on IPX node 1
- you would use:
-
-
- # ipx_internal_net add 0xab000000 1
-
-
-
- ipx_route
- The command allows you to manually modify the IPX routing table.
- For example to add a route to IPX network 39ab0222 via a router
- with node number 00608CC33C0F on IPX network 39ab0108:
-
-
- # ipx_route add 0x39ab0222 0x39ab0108 0x00608CC33C0F
-
-
-
- 8. Configuring your Linux machine as an IPX router.
-
- If you have a number of IPX segments that you wish to internetwork you
- need the services of a router. In the Novell environment there are two
- pieces of information which are necessary to be propagated around the
- network. They are the network routing information propagated using
- Novell RIP, and the service advertisement information propagated using
- Novell SAP. Any router must support both of these protocols to be
- useful in most situations.
-
- Linux has support for both of these protocols and can be fairly easily
- made to function as a fully Novell compliant router.
-
- The Linux kernel IPX support actually manages the IPX packet
- forwarding across interfaces, but it does this according to the rules
- coded into the IPX routing table. Linux needs a program to implement
- the Novell RIP and SAP to ensure that the IPX routing table is built
- correctly and updated periodically to reflect changes in the network
- status.
-
- Volker Lendecke has developed a routing
- daemon ipxripd that will do this for you. The mars_nwe package
- mentioned later includes an alternative routing daemon.
-
- You can find ipxripd at:
-
- sunsite.unc.edu
-
-
- or at Volkers home site at:
-
- ftp.gwdg.de
-
-
- Configuring your Linux machine to act as a router is very
- straightforward. The steps you must take are:
-
- 1. Build your kernel with IPX, Ethernet and /proc support.
-
- 2. Obtain, compile and install the ipxd daemon program.
-
- 3. Boot the new kernel and ensure that each of the Ethernet cards has
- been properly detected and there are no hardware conflicts.
-
- 4. Enable the IPX protocol on each of the interfaces using the
- ipx_interface command described above.
-
- 5. Start the ipxd daemon program.
-
- Consider the following simple network:
-
-
- IPX Addr: 0x01000000 802.2
- |--------------------------|
- |
- \_________________________
- \ Linux Router
- IPX Addr: 0x02000000 802.2 \
- |--------------------------| \ eth0/-----------\
- | \--====| |
- \_________________________ | IPX route |
- \ eth1| Table |
- IPX Addr: 0x03000000 etherII \----====| ^ |
- |--------------------------| | | |
- | eth2| IPXd |
- \______________________________/====| |
- | SAPd |
- IPX Addr: 0x04000000 etherII eth3| |
- |--------------------------| /====| |
- | | \___________/
- \______________________________/
-
-
-
- The configuration for the above network would look like:
-
-
- # ipx_interface add eth0 802.2 0x0100000000
- # ipx_interface add eth1 802.2 0x0200000000
- # ipx_interface add eth2 etherii 0x0300000000
- # ipx_interface add eth3 etherii 0x0400000000
- # ipxd
-
-
-
- You should then wait a moment or two and check your
- /proc/net/ipx_route file and you should see it populated with the IPX
- routes relevant to your configuration and any learned from any other
- routers in the network.
-
-
- 8.1. Do I need to configure an internal network ?
-
- Novell has a feature called an internal network, which it uses to
- simplify routing in situations where a host has more than one network
- device connected. This is useful in the case of a fileserver
- connected to multiple networks as it means that only one route needs
- to be advertised to reach the server regardless of which network you
- are attempting from.
- In the case of a configuration where you are not running a fileserver
- and your machine acting only as an IPX router the question is not as
- simple to answer. It has been reported that configuring for IPX/PPP
- works `better' if you also configure an internal network.
-
- In any case it is easy to do, but may require a rebuild of your
- kernel. When you are working through the kernel make config you must
- answer y when asked Full internal IPX network as illustrated:
-
-
-
- ...
- ...
- Full internal IPX network (CONFIG_IPX_INTERN) [N/y/?] y
- ...
- ...
-
-
-
- To configure the internal network interface, use the ipx_internal_net
- command described earlier in the IPX tools section. The main
- precaution to take is to ensure that they IPX network address you
- assign is unique on your network and that no other machine or network
- is using it.
-
-
- 9. Configuring your Linux machine as an NCP client.
-
- If you are a user of a mixed technology network that comprises both IP
- and IPX protocols it is likely that at some time or another you have
- wanted to have your Linux machine access data stored on a Novell
- fileserver on your network. Novell have long offered an NFS server
- package for their fileservers that would allow this, but if you are a
- small site or have only a small number of people interested in doing
- this it is difficult to justify the cost of the commercial package.
-
- Volker Lendecke has written a Linux
- filesystem kernel module that supports a subset of the Novell NCP that
- will allow you to mount Novell volumes into your Linux filesystem
- without requiring any additional products for your fileserver. Volker
- has called the package ncpfs and derived the necessary information
- mainly from the book "Netzwerkprogrammierung in C" by Manfred Hill and
- Ralf Zessin (further details of the book are contained within the
- README file in the ncpfs package).
-
- The software causes Linux to emulate a normal Novell workstation for
- file services. It also includes a small print utility that allows you
- to print to Novell print queues (This is documented in the Print
- Client section later). The ncpfs package will work with Novell
- fileservers of version 3.x and later, it will not work the Novell 2.x.
- The ncpfs client will also work with close Novell compatible products,
- but unfortunately some products that claim to be compatible aren't
- compatible enough. To use ncpfs with Novell 4.x fileservers, it is
- preferred to use the Novell server in bindery emulation mode. The NDS
- support is a very recent early beta addition to ncpfs and additionally
- its use may be prohibited in your country due to the inclusion of
- patented technology.
-
-
-
- 9.1. Obtaining ncpfs .
-
- The latest ncpfs package was designed to be built against the version
- 1.2.13 kernel or kernels later than 1.3.71 (this includes 2.x.x). If
- you not using a kernel in either of these categories then you will
- have to upgrade your kernel. The Kernel-HOWTO
- describes how to do this in detail.
-
- You can obtain the ncpfs package by anonymous ftp from Volker's home
- site at: ftp.gwdg.de or
- sunsite.unc.edu
- or mirror
- sites. The current version at the time of writing was:
-
- ncpfs-2.0.11.tgz or ncpfs-2.2.0.tgz which adds the NDS support.
-
-
- 9.2. Building ncpfs for kernel 1.2.13.
-
-
- Build a kernel with Ethernet and IPX support
- The first thing you need to do is ensure that your kernel has
- been built with IPX support enabled. In the 1.2.13 version
- kernel you need only ensure that you have answered Y to the
- question: 'The IPX protocol' as illustrated:
-
- ...
- ...
- Assume subnets are local (CONFIG_INET_SNARL) [y]
- Disable NAGLE algorithm (normally enabled) (CONFIG_TCP_NAGLE_OFF) [n]
- The IPX protocol (CONFIG_IPX) [n] y
- *
- * SCSI support
- ...
- ...
-
-
- You will also need to ensure that you include an appropriate driver
- for your Ethernet card. If you do not know how to do this then you
- should read the Ethernet-HOWTO .
-
- You can then proceed to build your kernel. Make sure you remember
- to run lilo to install it when you have finished.
-
-
- Untar the ncpfs software
-
- # cd /usr/src
- # tar xvfz ncpfs-2.0.11.tgz
- # cd ncpfs
-
-
-
- Check the Makefile
- If you intend to use kerneld to autoload the ncpfs kernel module
- then you must uncomment the line in the Makefile that refers to:
- KERNELD. If you are unsure what this means then you should read
- the Kernel-HOWTO to familiarise yourself
-
- with kernel module configuration.
-
-
- Make the ncpfs software
- The software should compile cleanly with no other configuration
- necessary:
-
- # make
-
-
-
- Copy the IPX tools somewhere useful if you don't already have them.
- After the make has completed you should find all of the tools
- you need in the ncpfs/bin directory. You can use:
-
-
-
- # make install
-
-
-
- to install the tools in Volkers choice of directories. If you are
- running on an ELF based system then you will need to rerun
- `ldconfig -v' to ensure that the shared library is able to be
- found.
-
-
- Copy the ncpfs.o module somewhere useful if necessary.
- If you are compiling for a 1.2.* kernel then you will find a
- file called ncpfs.o in the ncpfs/bin directory after the make
- has completed. This is the ncpfs kernel module. You should copy
- this somewhere useful. On my debian system I have copied it to
- the /lib/modules/1.2.13/fs directory and added ncpfs to the
- /etc/modules file so that it will be automatically started at
- boot time. If you are using some other distribution you should
- find where it keeps its modules and copy it there, or just copy
- it to your /etc directory. To load the modules manually you need
- to use the command:
-
- # insmod ncpfs.o
-
-
-
- 9.3. Building ncpfs for kernels 1.3.71++/2.0.*.
-
- For the latest version of ncpfs you must use kernel 1.3.71 or newer,
- this includes the 2.0.* kernels.
-
- If you intend using a kernel that is version 1.3.71 or newer then the
- ncpfs kernel code has been included in the standard kernel
- distribution. You need only answer Y to:
-
-
- Networking options --->
- ...
- ...
- <*> The IPX protocol
- ...
- Filesystems --->
- ...
- ...
- <*> NCP filesystem support (to mount NetWare volumes)
- ...
-
-
-
- You will still need to follow the instructions for building for
- kernels 1.2.* so that you can build the tools but there will not be a
- module file for you to install.
-
-
-
- 9.4. Configuring and using ncpfs .
-
-
- Configure the IPX network software
- There are two ways of configuring the IPX network software. You
- can manually configure all of your IPX network information or
- you can choose to let the software determine for itself some
- reasonable settings using the command:
-
-
-
- # ipx_configure --auto_interface=on --auto_primary=on
-
-
-
- This should be reasonable in most circumstances, but if it doesn't
- work for you then read the 'IPX tools' section above to configure
- your software manually. Problems have been noted using this on
- networks containing Windows '95 clients.
-
-
- Test the configuration
- After your IPX network is configured you should be able to use
- the slist command to see a list of all of the Novell fileserver
- on your network:
-
- # slist
-
-
- If the slist command displays a message like: ncp_connect: Invalid
- argument then your kernel probably does not support IPX. Check that
- you have actually booted off the appropriate kernel. When you boot
- you should see messages about 'IPX' and 'ncpfs' in the system
- startup messages. If the slist command does not list all of your
- fileservers then you may need to use the manual network configura-
- tion method.
-
-
- Mount a Novell(tm) server or volume.
- If your IPX network software is working ok you should now be
- able to mount a Novell fileserver or volume into your Linux
- filesystem. The ncpmount command is used for this purpose and
- requires that you specify at least the following information:
-
- 1. The fileserver name
-
- 2. (optionally) The fileserver directory to mount
-
- 3. The fileserver login id. If it has a password you will also
- need that.
-
- 4. The mount point ie. where you want the mount to go. This will
- be an existing directory on your machine.
-
- There is an equivalent ncpumount command to unmount a mounted
- NCP filesystem. The NCP filesystems will be unmounted cleanly if
- you shutdown your machine normally, so you needn't worry about
- ncpumounting your filesystems manually before a halt or
- shutdown.
-
- An example command to mount fileserver ACCT_FS01, with a login
- id of guest with no password, under the /mnt/Accounts directory
- might look like the following:
-
-
- # ncpmount -S ACCT_FS01 /mnt/Accounts -U guest -n
-
-
- Note the use of the -n option to indicate that no password is
- required for the login. The same login specifying a password of
- secret would look like:
-
- # ncpmount -S ACCT_FS01 /mnt/Accounts -U guest -P secret
-
-
- If you don't specify either the -n or the -P options you will be
- prompted for a password.
-
-
- Check the mount
- If the mount is successful you will find all the volumes
- accessible to the userid used for login listed as directories
- under the mount point. You should then also be able to traverse
- the directory structure to find other files. You may
- alternatively use the -V option to mount a single volume.
-
- NCP does not provide uid or gid ownership of files. All the
- files will have the permission and ownership assigned to the
- mount point directory restricted by trustee permissions on the
- Novell server. Bear this in mind when sharing mounts between
- Linux users.
-
-
- Configure mounts to be automatically performed.
- If you have some need to permanently have an ncp mount then you
- will want to configure the commands above into your rc files so
- that they occur automatically at boot time. If your distribution
- doesn't already provide some way of configuring IPX like debian
- then I recommend you place them in your /etc/rc.local file if
- you have one. You might use something like:
-
-
- #
- # Start the ncp filesystem
-
- /sbin/insmod /lib/modules/1.2.13/fs/ncpfs.o
-
- # configure the IPX network
- ipx_configure --auto_interface=on --auto_primary=on
-
- # guest login to the Accounting fileserver
- ncpmount -S ACCT_FS01 /mnt/Accounts -U guest -n
-
- #
-
-
-
- There is another means of configuring NCP mounts and that is by
- building a $HOME/.nwclient file. This file contains details of tem-
- porary or user specific NCP mounts that would be performed regu-
- larly. It allows you to store the details of mounts so that you can
- recreate them without having to specify all of the detail each
- time.
-
- Its format is quite straightforward:
-
-
-
- # The first entry is the 'preferred server' entry and is
- # used whenever you do not specify a server explicitly.
- #
- # User TERRY login to DOCS_FS01 fileserver with password 'password'
- DOCS_FS01/TERRY password
- #
- # Guest login to the ACCT_FS01 fileserver with no password.
- ACCT_FS01/GUEST -
-
-
-
- To activate these mounts you could use:
-
-
- $ ncpmount /home/terry/docs
-
-
-
- to mount: DOCS_FS01 with a login of TERRY under the
- /home/terry/docs directory. Note that this entry was chosen because
- no fileserver was specified in the mount command. If the following
- command were used:
-
-
- $ ncpmount -S ACCT_FS01 /home/terry/docs
-
-
-
- then a GUEST login to ACCT_FS01 would be mounted there instead.
-
- Note: for this mechanism to work the permissions of the
- $HOME/.nwclient file must be 0600 so you would need to use the
- command:
-
-
- $ chmod 0600 $HOME/.nwclient
-
-
-
- If non-root users are to be allowed to use this mechanism then the
- ncpmount command must be Set Userid Root, so you would need to give
- it permissions:
-
-
- # chmod 4755 ncpmount
-
-
-
- Try out the nsend utility
- a utility to send messages to Novell users is also included in
- the package, it is called nsend and is used as follows:
-
- # nsend rod hello there
-
-
- would send the message "hello there" to a logged in user "rod" on
- your "primary" fileserver (the first one appearing in your
- .nwclient file. You can specify another fileserver with the same
- syntax as for the ncpmount command.
-
- 10. Configuring your Linux machine as an NCP server.
-
- There are two packages available that allow Linux to provide the
- functions of a Novell Fileserver. They both allow you to share files
- on your linux machine with users using Novell NetWare client software.
- Users can attach and map filesystems to appear as local drives on
- their machines just as they would to a real Novell fileserver. You may
- want to try both to see which best serves your intended purpose.
-
-
- 10.1. The mars_nwe package.
-
- Martin Stover developed mars_nwe to enable linux
- to provide both file and print services for NetWare clients.
-
- In case you are wondering about the name: mars_nwe is Martin Stovers
- Netware Emulator.
-
-
- 10.1.1. Capability of mars_nwe .
-
- mars_nwe implements a subset of the full Novell NCP for file services,
- disk based bindery and also print services. It is likely to contain
- bugs but there are many people using it now and the number of bugs is
- steadily decreasing as new versions are released.
-
-
- 10.1.2. Obtaining mars_nwe .
-
- You can obtain mars_nwe from ftp.gwdg.de
- or from
- .
-
- The version current at the time of writing was:
- mars_nwe-0.99.pl10.tgz.
-
-
- 10.1.3. Building the mars_nwe package.
-
-
- Build a kernel with Ethernet and IPX Support
- In the 1.2.13 version kernel you need only ensure that you have
- answered Y to the question: 'The IPX protocol' and N to the
- question: `Full internal IPX network' as illustrated:
-
- ...
- ...
- The IPX protocol (CONFIG_IPX) [n] y
- ...
- ...
- Full internal IPX network (CONFIG_IPX_INTERN) [N/y/?] n
- ...
- ...
-
-
- In newer kernels a similar process is adopted but the actual text
- of the prompt may have changed slightly.
-
- You will also need to ensure that you include an appropriate driver
- for your Ethernet card. If you do not know how to do this then you
- should read the Ethernet-HOWTO .
-
- You can then proceed to build your kernel. Make sure you remember
- to run lilo to install it when you have finished.
-
-
- Untar the mars_nwe package.
-
-
- # cd /usr/src
- # tar xvfz mars_nwe-0.99.pl10.tgz
-
-
-
- Make mars_nwe.
- To make the package is very simple. The first step is to simply
- run make, this will create a config.h file for you. Next you
- should look at and edit the config.h file if necessary. It
- allows you to configure items such as the installation
- directories that will be used and the maximum number of sessions
- and volumes that the server will support. The really important
- entries to look at are:
-
- FILENAME_NW_INI the location of the initialisation file
- PATHNAME_PROGS where the executable support programs will be found.
- PATHNAME_BINDERY where the 'bindery' files will go.
- PATHNAME_PIDFILES the directory for the 'pid' files to be written.
- MAX_CONNECTIONS the maximum number of simultaneous connections allowed.
- MAX_NW_VOLS the maximum number of volumes mars_nwe will support.
- MAX_FILE_HANDLES_CONN the maximum number of open files per connection.
- WITH_NAME_SPACE_CALLS if you want to support ncpfs clients.
- INTERNAL_RIP_SAP whether you want mars_nwe to provide rip/sap routing.
- SHADOW_PWD whether you use shadow passwords or not.
-
-
-
- The defaults will probably be ok but you should check anyway.
-
- When this is done:
-
-
- # make
- # make install
-
-
-
- will build the servers and install them in the appropriate
- directory. The installation script also installs the configuration
- file /etc/nwserv.conf.
-
-
- Configure the server.
- Configuration is fairly simple. You need to edit the
- /etc/nwserv.conf file. The format of this file may at first look
- a little cryptic, but it is fairly straightforward. The file
- contains a number of single line configuration items. Each line
- is whitespace delimited and begins with a number that indicates
- the contents of the line. All characters following a '#'
- character are considered a comment and ignored. Martin supplies
- an example configuration file in the package, but I'll present
- what I consider to be a simplified example to offer an
- alternative for you.
-
-
-
- # VOLUMES (max. 5)
- # Only the SYS volume is compulsory. The directory containing the SYS
- # volume must contain the directories: LOGIN, PUBLIC, SYSTEM, MAIL.
- # The 'i' option ignores case.
- # The 'k' option converts all filenames in NCP requests to lowercase.
- # The 'm' option marks the volume as removable (useful for cdroms etc.)
- # The 'r' option set the volume to read-only.
- # The 'o' option indicates the volume is a single mounted filesystem.
- # The 'P' option allows commands to be used as files.
- # The 'O' option allows use of the OS/2 namespace
- # The 'N' option allows use of the NFS namespace
- # The default is upper case.
- # Syntax:
- # 1
-
- 1 SYS /home/netware/SYS/ # SYS
- 1 DATA /home/netware/DATA/ k # DATA
- 1 CDROM /cdrom kmr # CDROM
-
- # SERVER NAME
- # If not set then the linux hostname will be converted to upper case
- # and used. This is optional, the hostname will be used if this is not
- # configured.
- # Syntax:
- # 2
-
- 2 LINUX_FS01
-
- # INTERNAL NETWORK ADDRESS
- # The Internal IPX Network Address is a feature that simplifies IPX routing
- # for multihomed hosts (hosts that have ports on more than one IPX network).
- # Syntax:
- # 3 []
- # or:
- # 3 auto
- #
- # If you use 'auto' then your host IP address will be used. NOTE: this may
- # be dangerous, please be sure you pick a number unique to your network.
- # Addresses are 4byte hexadecimal (the leading 0x is required).
-
- 3 0x49a01010 1
-
-
- # NETWORK DEVICE(S)
- # This entry configures your IPX network. If you already have your
- # IPX network configured then you do not need this. This is the same as
- # using ipx_configure/ipx_interface before you start the server.
- # Syntax:
- # 4 []
- # Frame types: ethernet_ii, 802.2, 802.3, SNAP
-
- 4 0x39a01010 eth0 802.3 1
-
- # SAVE IPX ROUTES AFTER SERVER IS DOWNED
- # Syntax:
- # 5
- # 0 = don't save routes, 1 = do save routes
-
- 5 0
-
- # NETWARE VERSION
- # Syntax:
- # 6
- # 0 = 2.15, 1 = 3.11
-
- 6 1
- # PASSWORD HANDLING
- # Real Novell DOS clients support a feature which encypts your
- # password when changing it. You can select whether you want your
- # mars server to support this feature or not.
- # Syntax
- # 7
- # is:
- # 0 to force password encryption. (Clients can't change password)
- # 1 force password encryption, allow unencrypted password change.
- # 7 allow non-encrypted password but no empty passwords.
- # 8 allow non-encrypted password including empty passwords.
- # 9 completely unencrypted passwords (doesn't work with OS/2)
-
- 7 1
-
- # MINIMAL GID UID rights
- # permissions used for attachments with no login. These permissions
- # will be used for the files in your primary server attachment.
- # Syntax:
- # 10
- # 11
- # are from /etc/passwd, /etc/groups
-
- 10 200
- 11 201
-
- # SUPERVISOR password
- # May be removed after the server is started once. The server will
- # encrypt this information into the bindery file after it is run.
- # You should avoid using the 'root' user and instead use another
- # account to administer the mars fileserver.
- #
- # This entry is read and encrypted into the server bindery files, so
- # it only needs to exist the first time you start the server to ensure
- # that the password isn't stolen.
- #
- # Syntax:
- # 12 []
-
- 12 SUPERVISOR terry secret
-
- # USER ACCOUNTS
- # This associates NetWare logins with unix accounts. Password are
- # optional.
- # Syntax:
- 13 []
-
- 13 MARTIN martin
- 13 TERRY terry
-
- # LAZY SYSTEM ADMIN CONFIGURATION
- # If you have a large numbers of users and could not be bothered using
- # type 13 individual user mappings, you can automatically map mars_nwe
- # logins to linux user names. BUT, there is currently no means of making
- # use of the linux login password so all users configured this way are
- # will use the single password supplied here. My recommendation is not
- # to do this unless security is absolutely no concern to you.
- # Syntax:
- # 15
- # is: 0 - don't automatically map users.
- # 1 - do automatically map users not configured above.
- # 99 - automatically map every user in this way.
-
- 15 0 duzzenmatta
-
- # SANITY CHECKING
- # mars_nwe will automatically ensure that certain directories exist if
- # you set this flag.
- # Syntax:
- # 16
- # is 0 for no, don't, or 1 for yes, do.
-
- 16 0
-
- # PRINT QUEUES
- # This associates NetWare printers with unix printers. The queue
- # directories must be created manually before printing is attempted.
- # The queue directories are NOT lpd queues.
- # Syntax:
- # 21
-
- 21 EPSON SYS:/PRINT/EPSON lpr -h
- 21 LASER SYS:/PRINT/LASER lpr -Plaser
-
- # DEBUG FLAGS
- # These are not normally needed, but may be useful if are you debugging
- # a problem.
- # Syntax:
- #
- #
- # 100 = IPX KERNEL
- # 101 = NWSERV
- # 102 = NCPSERV
- # 103 = NWCONN
- # 104 = start NWCLIENT
- # 105 = NWBIND
- # 106 = NWROUTED
- # 0 = disable debug, 1 = enable debug
-
- 100 0
- 101 0
- 102 0
- 103 0
- 104 0
- 105 0
- 106 0
-
- # RUN NWSERV IN BACKGROUND AND USE LOGFILE
- # Syntax:
- # 200
- # 0 = run NWSERV in foreground and don't use logfile
- # 1 = run NWSERV in background and use logfile
-
- 200 1
-
- # LOGFILE NAME
- # Syntax:
- # 201
-
- 201 /tmp/nw.log
-
- # APPEND LOG OR OVERWRITE
- # Syntax:
- # 202
- # 0 = append to existing logfile
- # 1 = overwrite existing logfile
-
- 202 1
-
- # SERVER DOWN TIME
- # This item sets the time after a SERVER DOWN is issued that the
- # server really goes down.
- # Syntax:
- # 210
- # in seconds. (defaults 10)
-
- 210 10
-
- # ROUTING BROADCAST INTERVAL
- # The time is seconds between server broadcasts
- # Syntax:
- # 211
- # in seconds. (defaults 60)
-
- 211 60
-
- # ROUTING LOGGING INTERVAL
- # Set how many broadcasts take place before logging of routing
- # information occurs.
- # Syntax:
- # 300
-
- 300 5
-
- # ROUTING LOGFILE
- # Set the name of the routing logfile
- # Syntax:
- # 301
-
- 301 /tmp/nw.routes
-
- # ROUTING APPEND/OVERWRITE
- # Set whether you want to append to an existing log file or
- # overwrite it.
- # Syntax:
- # 302
- # is 0 for append, 1 for create/overwrite
-
- 302 1
-
- # WATCHDOG TIMING
- # Set the timing for watchdog messages that ensure the network is
- # still alive.
- # Syntax:
- # 310
- # = 0 - always send watchdogs
- # < 0 - (-ve) for disable watchdogs
- # > 0 - send watchdogs when network traffic
- # drops below 'n' ticks
-
- 310 7
-
- # STATION FILE
- # Set the filename for the stations file which determine which
- # machines this fileserver will act as the primary fileserver for.
- # The syntax of this file is described in the 'examples' directory
- # of the source code.
- # Syntax:
- # 400
-
- 400 /etc/nwserv.stations
-
- # GET NEAREST FILESERVER HANDLING
- # Set how SAP Get Nearest Fileserver Requests are handled.
- # Syntax:
- # 401
- # is: 0 - disable 'Get Nearest Fileserver' requests.
- # 1 - The 'stations' file lists stations to be excluded.
- # 2 - The 'stations' file lists stations to be included.
-
- 401 2
-
-
-
- Start the server
- If you've configured the server to expect external programs to
- configure your network and/or provide the routing function then
- you should start those before starting the server. Presuming you
- have configured the server so that it will configure your
- interfaces for you and provide the routing services you need
- only issue the command:
-
-
- # nwserv
-
-
-
- Test the server
- To test the server you should first try to attach and login from
- a NetWare client on your network. You then set a CAPTURE from
- the client and attempt a print. If both of these are successful
- then the server is working.
-
-
- 10.2. The lwared package.
-
- Ales Dryak developed lwared to allow Linux to
- function as an NCP based fileserver.
-
- Ales has called the package lwared, an abbreviation for LinWare
- Daemon.
-
-
- 10.2.1. Capability of lwared .
-
- The lwared server is capable of providing a subset of the full
- function of the Novell NCP. It incorporates messaging but it does not
- provide any printing facilities at all. It does not currently work
- very well with either Windows95 or Windows NT clients. The lwared
- server relies on external programs to build and update the IPX routing
- and SAP tables. Misbehaving clients can cause the server to crash.
- Importantly, filename translation facilities have not been included.
-
- The server does work for NETX and VLM NetWare shells.
-
-
- 10.2.2. Obtaining lwared
-
- The lwared package can be built for any kernel newer than 1.2.0, I
- recommend you use version 1.2.13 as no kernel patches are required if
- you do. Some of the IPX functionality has changed with the version
- 1.3.* kernels and this means that patches are now required to make it
- work properly. Appropriate patches are included for the new kernels,
- so if you must use an alpha kernel you should still be able to get
- lwared to work properly for you.
-
- You can obtain the lwared package by anonymous ftp from:
- klokan.sh.cvut.cz
-
-
- or from:
-
- sunsite.unc.edu
- or mirror
- sites. The current version at the time of writing was:
- lwared-0.95.tar.gz
-
-
- 10.2.3. Building lwared
-
-
- Untar the lwaredpackage
- Something like:
-
- # cd /usr/src
- # tar xvpfz lwared-0.95.tar.gz
-
-
-
- Build a kernel with Ethernet and IPX support
- If you are using an alpha 1.3.* kernel then you should try and
- use kernel version 1.3.17 or newer because the supplied patches
- were built against it. 1.3.* kernels older than 1.3.17 will
- require hand patching to install. (some information on how to do
- this is included in the INSTALL file in the package.). To
- install the patches against a 1.3.17 kernel or newer you should
- try:
-
- # make patch
-
-
-
- After applying the patches if necessary, the next thing you need to
- do is ensure that your kernel has been built with IPX support
- enabled. In the 1.2.13 version kernel you need only ensure that you
- have answered Y to the question: 'The IPX protocol' as illustrated:
-
- ...
- ...
- Assume subnets are local (CONFIG_INET_SNARL) [y]
- Disable NAGLE algorithm (normally enabled) (CONFIG_TCP_NAGLE_OFF) [n]
- The IPX protocol (CONFIG_IPX) [n] y
- *
- * SCSI support
- ...
- ...
-
-
- In newer kernels a similar process is adopted by the actual text of
- the prompt may have changed slightly.
-
- You will also need to ensure that you include an appropriate driver
- for your Ethernet card. If you do not know how to do this then you
- should read the Ethernet-HOWTO .
-
- You can then proceed to build your kernel. Make sure you remember
- to run lilo to install it when you have finished.
-
-
- Compile and install lwared.
- To compile lwared you should first check, edit if necessary, the
- server/config.h file. This file contains various settings that
- will govern the way your server will behave when it is running.
- The defaults are reasonable, though you might want to check that
- the directories specified for the log files and configuration
- files suit your system.
-
- # make depend
- # make
- # make install
-
-
- I found that the 'make depend' complained about not finding the
- float.h file on my system but appeared to work anyway. I also
- found that when I tried compiling with gcc 2.6.3 I found I had to
- change the line:
-
- #include
-
-
- to
-
- #include
-
-
- in lib/ipxkern.c as this file changed name sometime.
-
- The 'make install' will attempt to install the server and routing
- daemon programs into your /usr/sbin directory, the lwpasswd program
- into your /usr/bin directory, the IPX utility programs will be
- installed into your /sbin directory and last but not least the
- manual pages will go into the /usr/man directory structure. If any
- of these locations are not suitable for your system then you should
- edit the relevant Makefile and change the target directories to
- suit.
-
-
-
- 10.2.4. Configuring and using lwared
-
- Now the fun bit!
-
-
- Configuring the IPX network
- The first thing you must do is configure your Ethernet
- interfaces to support the IPX networks your server will support.
- To do this you will need to know the IPX network addresses for
- each of your LAN segments, which Ethernet device (eth0, eth1
- etc.) is on which segment, what frame type (802.3, EtherII etc.)
- each LAN segment uses and what Internal Network address your
- server should use (this is really needed if your server will
- service more than one LAN segment). A configuration for a
- server that is on two dis-similar segments with IPX network
- addresses 23a91300 and 23a91301 and internal network address
- bdefaced might look like:
-
- # ipx_internal_net add BDEFACED 1
- # ipx_interface add eth0 802.3 23a91300
- # ipx_interface add eth1 etherii 23a91301
-
-
-
- Start the routing daemons
- The kernel software itself actually does the IPX packet
- forwarding as it does for IP, but the kernel requires additional
- programs to manage the routing table updates. In the case of IPX
- two daemons are needed and both are supplied with lwared:
- ipxripd manages the IPX routing information and ipxsapd manages
- the SAP information. To start the daemons you need only specify
- the location of where they should write their log messages:
- # ipxripd /var/adm/ipxrip
- # ipxsapd /var/adm/ipxsap
-
-
-
- Configure the lwared server
- There are two files that you must manually configure to allow
- user login to your lwared server. They are:
-
-
-
- /etc/lwpasswd
- This is where LinWare user account information is kept. The
- lwpasswd program is to keep it up to date. In its simplest
- form the /etc/lwpasswd file looks like:
-
- ales:
- terryd:
- guest:
-
-
- Its format is a simple list of login id followed by a ':' char-
- acter and then the encrypted version of the login passwd. A cou-
- ple of important caveats here: No encrypted password means no
- password, LinWare users must have Linux accounts, that is any
- user you place in /etc/lwpasswd must also appear in /etc/passwd
- and root is the only account that can change the password of
- another LinWare user. If you are logged in as root you can
- change the password of a LinWare user as this transcript demon-
- strates:
-
- # lwpasswd rodg
- Changing password for RODG
- Enter new password:
- Re-type new password:
- Password changed.
-
-
-
- /etc/lwvtab
- This is the LinWare volume tables and it stores information
- about what directories should be made available to LinWare
- users (this file is similar in nature to the NFS /etc/exports
- file). A simple example of its format is as follows:
-
- SYS /lwfs/sys
- DATA /lwfs/data
- HOME /home
-
-
- The format is simple: Volume name followed by whitespace fol-
- lowed by Linux directory to export. You must have at least an
- entry for the SYS volume for the server to start. If you intend
- your DOS based users to be able use your LinWare server as their
- primary server then you must install a standard SYS volume
- directory structure underneath the directory you export as your
- SYS volume. Since these files are proprietary and copyright to
- the Novell corporation you should have a license for these. If
- you users will be using a Novell fileserver as their primary
- server then this will not be necessary.
-
-
- Start the lwared server.
- tada!
-
- # lwared
-
-
- It is almost an anticlimax isn't it ? Ok so you've got a question,
- right? What is the fileserver name that is being advertised ? If
- you started the server as shown then the LinWare server name being
- advertised will be based on what is returned by the Linux hostname.
- If you'd like it to be something else then you can give the server
- the name when you start it, for example:
-
- # lwared -nlinux00
-
-
- would start the server with the name linux00.
-
-
- Test the lwared server.
- The very first thing to test is that your LinWare server appears
- in an slist from a DOS client on your network. The slist program
- is stored on the SYS volume of a Novell fileserver so you must
- do this from a machine that is already logged in somewhere. If
- this is not successful then check that ipxsapd and lwared are
- both running. If the slist is successful then you should try
- attaching to the server and mapping a volume:
-
- C:> attach linux00/ales
- ...
- ...
- C:> map l:=linux00/data:
- C:> l:
-
-
- You should then be able to treat the new map just like any other
- map. The file permissions you will have will be based on those
- allowed to the linux account that parallels your LinWare login.
-
-
-
- 11. Configuring your Linux machine as a Novell Print Client.
-
- The ncpfs package includes two small programs that allow you to handle
- printing from you Linux machine to a printer attached to a Novell
- print server. The nprint command allows you to print to a file to a
- NetWare print queue. The pqlist command allows you the list the
- available print queues on a NetWare server.
-
- To obtain and install these commands just follow the instructions
- relating to the NCP client described earlier.
-
- Both commands require that you supply username and password so you
- might normally consider building some shell scripts to make the task
- of printing easier.
-
- An example might look like:
-
-
- # pqlist -S ACCT_FS01 -U guest -n
- # nprint -S ACCT_FS01 -q LASER -U guest -n filename.txt
-
-
-
- The login syntax is similar to the ncpmount command. The examples
- above assume that fileserver ACCT_FS01 has a guest account with no
- password, that a print queue called LASER exists and that guest is
- allowed to print to it.
- On my Linux boxen I have a short shell script for each Novell printer.
- This can then be used as a print filter to allow printing using the
- standard Linux spooler.
-
-
- 12. Configuring your Linux machine as a Novell Print Server.
-
- A program to allow your Linux machine to act as a print server on a
- Netware network is included in the ncpfs package. For instructions on
- how to obtain and build, it follow the directions in the `Netware
- client' section above. Alternatively, support is included in the
- mars_nwe package.
-
-
-
- 12.1. Prerequisites
-
- Configuration is quite straightforward but relies on you already
- having your printer configuration completed and working under Linux.
- This is covered in the Printing-HOWTO in some
- depth.
-
-
- 12.2. Configuration
-
- When you have a working printer configuration, and you have built and
- installed the pserver utility then you need to add commands to start
- it into your rc files.
-
- Exactly what command will use will depend on depend on exactly how you
- want it to operate, but in its simplest form something like the
- following will work:
-
-
-
- # pserver -S ACCT_01 -U LASER -P secret -q LASERJET
-
-
-
- This example asks the pserver utility to login in to the ACCT_01
- fileserver with username LASER and password secret and to take jobs
- from the LASERJET print queue. When an incoming print job is received
- it will use the default print command of lpr to feed the print job to
- the Linux print daemon. The print queue must already be defined on the
- fileserver and the username must have server priveliges for the queue.
-
- You could if you wished use any Linux command to accept and print the
- print job. The -c argument allows you to specify the exact print
- command. For example:
-
-
- # pserver -S ACCT_01 -U LASER -P secret -q LASERJET -c "lpr -Plaserjet"
-
-
-
- would do exactly the same as the previous example except it would send
- the job to the laserjet printcap configuration instead of the default
- one.
-
-
- 13. An overview of the ncpfs user and adminstration commands
-
- Recent versions of Volker's ncpfs package include a range of user and
- administration commands that you might want to use. The tools are
- built and installed as part of the ncpfs installation process, so if
- you haven't already, follow the instructions supplied in the Novell
- Client section above to build and install them.
-
- Detailed information is available in the supplied man pages but a
- brief summary of the commands is as follows;
-
-
- 13.1. User commands.
-
-
- ncopy
- Network Copy - allows efficient file copies to be performed by
- using a Netware function rather than a copy across the network.
-
- nprint
- Network Print - allows you to print a file to a Netware print
- queue on a Netware server.
-
- nsend
- Network Send - allows you to send messages to other users on a
- Netware server.
-
- nwbols
- List Bindery Objects - allows you to list the bindery contents
- of a Netware server.
-
- nwboprops
- List Properties of a Bindery Object - allows you to the
- properties of a Netware bindery object.
-
- nwbpset
- Set Bindery Property - allows you to set the properties of a
- Netware bindery object.
-
- nwbpvalues
- Print Netware Bindery Objects Property Contents - allows you to
- print the contents of a Netware bindery property.
-
- nwfsinfo
- Fileserver Information - prints some summary information about a
- Netware server.
-
- nwpasswd
- Netware Password - allows you to change a Netware users
- password.
-
- nwrights
- Netware Rights - displays the rights associated with a
- particular file or directory.
-
- nwuserlist
- Userlist - lists the users currently logged into a Netware
- fileserver.
-
- pqlist
- Print Queue List - displays the contents of a Netware print
- queue.
-
- slist
- Server List - displays a list of know Netware fileserver.
-
-
-
- 13.2. Administration tools.
-
-
- nwbocreate
- Create a Bindery Object - allows you to create a Netware bindery
- object.
-
- nwborm
- Remove Bindery Object - allows you to delete a Netware bindery
- object.
-
- nwbpadd
- Add Bindery Property - allows you to set the value of an
- existing property of a Netware bindery object.
-
- nwbpcreate
- Create Bindery Property - allows you to create a new property
- for an existing Netware bindery object.
-
- nwbprm
- Remove Bindery Property - allows you to remove a property from a
- Netware bindery object.
-
- nwgrant
- Grant Trustee Rights - allows you to assign trustee rights to a
- directory on a Netware fileserver.
-
- nwrevoke
- Revoke Trustee Rights - allows you to remove trustee rights from
- a directory on a Netware fileserver.
-
-
-
- 14. Configuring PPP for IPX support.
-
- New versions of the pppd PPP daemon for Linux have support that allows
- you to carry IPX packets across a PPP serial link. You need at least
- version ppp-2.2.0d of the daemon. See the PPP-HOWTO
- for details on where to find it. When you compile pppd you must ensure
- you enable the IPX support by adding the following two lines:
-
-
-
- IPX_CHANGE = 1
- USE_MS_DNS = 1
-
-
-
- to: /usr/src/linux/pppd-2.2.0f/pppd/Makefile.linux.
-
- The IPX_CHANGE is what configures the IPX support into PPP. The
- USE_MS_DNS define allows Microsoft Windows95 machines to do Name
- Lookups.
-
- The real trick to getting it to work in knowing how to configure it.
-
- There are many ways of doing this, but I'm only going to describe the
- two that I've received any information on. I've tried neither yet, so
- consider this section experimental, and if you get something to work,
- please let me know.
-
-
-
- 14.1. Configuring an IPX/PPP server.
-
- The first thing you need to do is configure your Linux machine as an
- IP/PPP server. Don't panic! This isn't difficult. Again, follow the
- instructions in the PPP-HOWTO and you should be
- pretty much ok. When you have this done there are a couple of simple
- modifications you need to make to get IPX working over the same
- configuration.
-
-
- 14.1.1. First steps.
-
- One of the first steps you must take is to configure your linux
- machine as an IPX router as described in the appropriate section
- earlier in this document. You won't need to use the ipx_route command
- for the ppp interface because pppd will configure these for you as it
- does for IP. When you have the ipxd daemon running it will
- automatically detect any new IPX interfaces and propogates routes for
- them. In this way your dialup hosts will be seen by other machines
- automatically when they connect.
-
-
-
- 14.1.2. Design.
-
- When you are running as a server it will normally be your
- responsibility to assign network address to each of the PPP links when
- they are established. This is an important point, each PPP link will
- be an IPX network and will have a unique IPX network address. This
- means that you must decide how you will allocate addresses and what
- what they will be. A simple convention is to allocate one IPX network
- address to each serial device that will support IPX/PPP. You could
- allocate IPX network addresses based on the login id of the connecting
- user, but I don't see any particularly good reason to do so.
-
- I will assume that this is what you have done, and that there are two
- serial devices (modems) that we will use. The addresses I've assigned
- in this contrived example are:
-
-
-
- device IPX Network Address
- ------ -------------------
- ttyS0 0xABCDEF00
- ttyS1 0xABCDEF01
-
-
-
- 14.1.3. Configure pppd .
-
- Configure your /etc/ppp/options.ttyS0 file as follows:
-
-
-
- ipx-network 0xABCDEF00
- ipx-node 2:0
- ipxcp-accept-remote
-
-
-
- and your /etc/ppp/options.ttyS1 file as:
-
-
- ipx-network 0xABCDEF01
- ipx-node 3:0
- ipxcp-accept-remote
-
-
-
- These will ask pppd to allocate the appropriate IPX network addresses
- to the link when the link is established, set the local node number to
- 2 or 3 and will let the remote node overwrite what the remote node
- number with what it thinks it is. Note that each of the addresses are
- hexadecimal numbers and that 0x is required at the start of the
- network address, but not required at the start of the node address.
-
- There are other places this information could be configured. If you
- have only one dialin modem then an entry could go into the
- /etc/ppp/options file. Alternatively this information can be passed on
- the command line to pppd.
-
-
- 14.1.4. Test the server configuration.
-
- To test the configuration you will need to have a client configuration
- that is known to work. When the caller dials in, logs in and pppd
- starts it will assign the network address, advise the client of the
- servers node number and negotiate the clients node number. When this
- has completed, and after ipxd has detected the new interface the
- client should be able to establish IPX connections to remote hosts.
-
-
- 14.2. Configuring an IPX/PPP client.
-
- In a client configuration, whether or not you configure your Linux
- machine as an IPX router depends on whether you have a local LAN that
- you wish to act as an IPX router for. If you are a standalone machine
- connecting to an IPX/PPP dialin server then you won't need to run
- ipxd, but if you have a LAN and wish all of the machines on the LAN to
- make use of the IPX/PPP route then you must configure and run ipxd as
- described. This configuration is much simpler because you do not have
- multiple serial devices to configure.
-
-
- 14.2.1. Configuring pppd
-
- The simplest configuration is one that allows the server to supply all
- of the IPX network configuration information. This configuration would
- be compatible with the server configuration described above.
-
- Again you need to add some options to your /etc/ppp/options file, they
- are:
-
-
- ipxcp-accept-network
- ipxcp-accept-remote
- ipxcp-accept-local
-
-
-
- These options tell pppd to act completely passively and accept all of
- the configuration details from the server. You could supply default
- values here for servers that don't supply details by adding ipx-
- network and ipx-node entries similar to the server configuration.
-
-
-
- 14.2.2. Testing the IPX/PPP client.
-
- To test the client you will need a known working server to dial into.
- After you have dialled in and pppd has run you should see the IPX
- details configured on your ppp0 device when you run the ifconfig
- command and you should be able to use ncpmount.
-
- I'm not sure whether you will have to manually add IPX routes so that
- you can reach distant fileserver or not. This seems likely. If anyone
- running this configuration could tell me I'd be grateful.
-
-
- 15. IPX tunnel over IP
-
- Many of you will be in a situation where you have two Novell Local
- Area Netorks with only an IP connection between them. How do you play
- multiplayer deathmatch DOOM for DOS via this arrangement you might ask
- ? Andreas Godzina has an answer for you in the form
- of ipxtunnel.
-
- ipxtunnel provides a bridge-like facility for IPX by allowing IPX
- packets to be encapsulated with tcp/ip datagrams so that they can be
- carried by a tcp/ip connection. It listens for IPX packets and when it
- hears one it wraps it within a tcp/ip datagram and routes it to a
- remote IP address that you specify. For this to work of course the
- machine that you route the encapsulated IPX must also be running a
- copy of the same version of ipxtunnel as you.
-
-
- 15.1. Obtaining ipxtunnel
-
- You can obtain ipxtunnel from sunsite.unc.edu
- or mirror
- sites.
-
-
- 15.2. Building ipxtunnel
-
- ipxtunnel built cleanly for me using the following commands:
-
-
- # cd /usr/src
- # tar xvfz .../ipxtunnel.tgz
- # cd ipxtunnel
- # make
-
-
-
- 15.3. Configuring ipxtunnel
-
- Configuration for ipxtunnel is easy. Lets say that your friends
- machine is gau.somewhere.com and your machine is called gim.sw.edu.
- ipxtunnel uses a configuration file called /etc/ipxtunnel.conf. This
- file allows you to specify the default UDP port to use for the tcp/ip
- connection, where to send the encapsulated data and which of your
- local interfaces ipxtunnel should listen on and deliver IPX packets
- to.
-
- A simple configuration file would look like the following:
-
-
-
- #
- # /etc/ipxtunnel.conf for gim.sw.edu
- #
- # The UDP port to use: (default 7666)
- port 7777
- #
- # The remote machine to send IPX packets to: (no default)
- remote gau.somewhere.com
- #
- # The local interfaces to listen for IPX on: (default eth0)
- interface eth0
- interface eth1
-
-
-
- Obviously the other machine would have a similar configuration file
- specifying this machine as a remote host.
-
-
- 15.4. Testing and using ipxtunnel
-
- ipxtunnel acts like an IPX bridge, so the IPX networks at either end
- of the link should probably be the same. Andreas has never tested the
- ipxtunnel in an environment that actually supports Novell file servers
- so if you do try this in a real environment let Andreas know if it
- works or not.
-
- If the ipxtunnel is working you should be able to start your DOOM
- machines up at each end of the link running IPX mode and they should
- see each other.
-
- Andreas has only used this code over good high speed lines and he
- makes no claim as to its performance when your link is low speed.
- Again, let him know what works for you and what doesn't.
-
-
-
- 16. Commercial IPX support for Linux.
-
-
-
- 16.1. Caldera'a Network Desktop
-
- Caldera Inc., produce a Linux distribution that features a range of
- commercially supported enhancements including fully functional Novell
- NetWare client support. The base distribution is the well respected
- Red Hat Linux Distribution and Caldera have added their "Network
- Desktop" products to this. The NetWare support provides a fully
- featured Novell NetWare client built on technology licensed from
- Novell Corporation. The client provides full client access to Novell
- 3.x and 4.x fileservers and includes features such as NetWare
- Directory Service (NDS) and RSA encryption.
-
- You can obtain much more information and ordering details from the:
- Caldera Inc Web Server .
-
- If you work within a Netware 4.x and/or NDS environment then the
- Caldera Netware Client is the only solution available.
-
- If you have a business critical application for Novell support for
- Linux then the Caldera product should be something you take a close
- look at.
-
-
- 17. Some Frequently Asked Questions
-
-
- Where can I find commercially supported IPX software for Linux ?
- The Caldera Corporation offers a fully licensed and fully
- supported Netware 3.x and 4.x client. You can obtain information
- about it from the Caldera Inc Web Server
- .
-
-
- Does the IPX software work with Arcnet/Token Ring/etc. ?
- The Linux IPX software does work with ArcNet and Token Ring
- interfaces. I haven't heard of anyone trying it with AX.25 yet.
- Configuration is the same as for configuring for ethernet except
- you will have to substitute appropriate device names in place of
- 'eth0' and appopriate hardware addresses where necessary.
-
-
- How do I configure more than one IPX interface ?
- If you have more than one interface in your machine you should
- use the ipx_interface command to manually configure each one,
- you should not use the `plug n play' configuration.
-
-
- How do I choose IPX addresses ?
- IPX networking is similar, but not identical to, IP networking.
- A major difference is the way that addresses are used. IPX does
- not use the concept of subnetworking and so the sort of
- associations that you have between network addresses and
- networks is different. The rules are fairly simple:
-
- o Every IPX network address must be unique on a wide area network.
- This includes Internal Network Addresses. Many organisations
- using IPX over a wide area network will have some sort of
- addressing standard that you should follow.
-
- o Every Host address on an individual network must be unique. This
- means that every host on each IPX network must have a uniquely
- assigned address. In the case of ethernet network this isn't
- difficult as the cards each have a unique address. In the case
- of IPX/PPP this means you must ensure that you allocate unique
- addresses to all hosts on the network, irrespective of which end
- of the link(s) they are connected. Host address do not need to
- be unique across a wide area network as the network address is
- used in combination with the host address to uniquely identify a
- host.
-
-
- What are frame types, which should I use ?
- There are a variety of frame types in use over which you can run
- IPX. The most common of these are described in the 'common
- terms' section of this document (under the `Frame Type entry').
-
- If you are installing your machine on an existing network then
- you must use whatever is already in use to allow you to
- interwork with the other hosts on the network, but if the
- installation is a brand new network you can use any of a range
- of protocols to carry your IPX traffic. My recommendation if
- you are configuring a brand new network and you need to carry
- both IPX and IP traffic is to use the Ethernet_II frame type.
-
-
- My Windows95 machines mess up my frame type autodetection ?
- Apparently they can, yeah. I could make nasty comments, but
- instead I'll just suggest that you use the manual frame type
- configuration instead of the automatic one. It is probably the
- better way anyway.
-
-
- Why do I get the message `invalid argument' when I configure IPX ?
- You are probably not running a kernel that supports IPX, either
- recompile your kernel so it does, or double check that you have
- actually used lilo to install and run the new kernel.
-
-
- Why do I get the message `package not installed' when I configure
- IPX ?
- You are probably not running a kernel that supports IPX, either
- recompile your kernel so it does, or double check that you have
- actually used lilo to install and run the new kernel.
-
-
- Why do I get the message `IPX support not in kernel' from pppd ?
- You've probably compiled IPX as a module and not ensured that it
- was loaded before started pppd.
-
-
- How do I NFS export a mounted NCP filesystem ?
- To use NFS to export an NCP filesystem you must mount it using
- the ncpmount -V option. This option allows you to mount only one
- volume of a fileserver instead of the usual mounting of all of
- them. When you do this your NFS daemon will allow you to export
- that filesystem in the usual way.
-
-
- Why doesn't slist work when I have an internel network with
- mars_nwe ?
- You must have the get nearest server enabled. That is, entry
- 401 in /etc/nwserv.conf should be 0 unless you have a reason for
- not responding to get nearest servers. If you just want slist
- to work and not respond to every get nearest server request,
- include your internal network and node number in
- /etc/nwserv.stations and set entry 401 in /etc/nwserv.conf to 2.
-
-
- Does ncpfs package work with mars_nwe ?
- Martin and Volker's code is slowly beginning to converge. Recent
- versions of mars_nwe have an option to enable it to work with
- ncpfs. You must enable the WITH_NAME_SPACE_CALLS in the
- mars_nwe config.h file.
-
-
- Is there any free DOS software to work with mars_nwe ?
- A contrived question deserves a contrived answer. I'm glad you
- asked, Martin has a package that he distributes alongside his
- mars_nwe package that offers free DOS client support for the
- mars_nwe server. You can find it at the same sites as the
- server, and it will be called mars_dosutils-0.01.tgz. It
- includes C source code for programs such as slist.exe,
- login.exe, map.exe etc. The source is compilable with
- Borland(tm) C.
-
How do I configure the kernel for IPX networking support?
@@ -1997,4 +60,6 @@ in the packet. Typical frame types used in NetWare networks
+* IPX-SPX HOWTO
+
diff --git a/LDP/guide/docbook/Linux-Networking/Internet.xml b/LDP/guide/docbook/Linux-Networking/Internet.xml
index c379c4d6..507e1e5b 100644
--- a/LDP/guide/docbook/Linux-Networking/Internet.xml
+++ b/LDP/guide/docbook/Linux-Networking/Internet.xml
@@ -15,7 +15,7 @@ term Intranet refers to the application of Internet technologies
inside an organisation mainly for the purpose of distributing and
making available information inside the company. Internet and Intranet
services offered by Linux include mail, news, WWW servers and many
-more that will be outlined further on in the 'Linux-Networking' guide.
+more that will be outlined further on in this document.
diff --git a/LDP/guide/docbook/Linux-Networking/Satellite.xml b/LDP/guide/docbook/Linux-Networking/Satellite.xml
index 1319acd5..3ecabaaa 100644
--- a/LDP/guide/docbook/Linux-Networking/Satellite.xml
+++ b/LDP/guide/docbook/Linux-Networking/Satellite.xml
@@ -15,1433 +15,6 @@
at http://www.fatamorgana.com/bertolinux and http://www.hack-it.net/How-To/Sat-HOWTO.html
.
- ______________________________________________________________________
-
- Table of Contents
-
-
-
- 1. Introduction
-
- 1.1 Introduction
- 1.2 Copyright
- 1.3 Translations
- 1.4 Credits
-
- 2. Background Knowledge
-
- 2.1 What about satellite
- 2.2 How does it work?
- 2.3 Other technologies
- 2.4 What is the max bandwidth?
- 2.5 How much does it cost?
- 2.5.1 Hardware costs
- 2.5.2 Account costs
- 2.6 What are the satellites used?
- 2.7 What ISPs give Sat Internet Access?
- 2.8 What else?
-
- 3. Technical Information
-
- 3.1 General working
- 3.2 Frequencies
- 3.3 DVB Receiver Card
- 3.4 Data Link Level DVB setting
- 3.5 TCP/IP working
- 3.6 Authentication
- 3.7 Services I can use with a sat connection
-
- 4. Requirements
-
- 4.1 Knowledge requirement
- 4.2 Hardware
- 4.3 Software
- 4.4 TV Software
- 4.4.1 Under Windows
- 4.4.2 Under Linux
-
- 5. Base setup
-
- 5.1 First: mounting
- 5.2 Calibrating
- 5.3 Double Feed
- 5.4 Data-link level adjusting
-
- 6. Configuration under Linux
-
- 6.1 Drivers installation
- 6.2 Setting up /etc/dvbd.conf
- 6.3 Dvbd daemon
- 6.4 How to config EON service
- 6.5 How to use Netsystem service
- 6.5.1 VPN connection
- 6.5.2 Patch for pppd
- 6.5.3 Routing settings
- 6.5.4 Patch for dvbd.c
- 6.5.5 Test it
- 6.5.6 Get performance better
- 6.5.7 Sharing Netsystem with many clients
- 6.6 How to use Sat Node service
- 6.7 OpenSky service under Linux
-
- 7. Configuration under Windows
-
- 7.1 EON
- 7.2 Netsystem
- 7.3 OpenSky
-
- 8. Appendix A - Notes
-
- 8.1 Translation Dynamic IP -> MAC Address
- 8.2 TCP Window
- 8.3 Download accelerator
- 8.3.1 Under Linux
- 8.3.2 Under Windows
-
- 9. Appendix B - Well Known Sat ISP setting value
-
- 9.1 EuropeOnLine
- 9.1.1 Transponder 113
- 9.1.2 Transponder 114
- 9.1.3 Transponder 115
- 9.1.4 Transponder 103
- 9.2 Netsystem
- 9.2.1 Transponder 119
- 9.3 Sat Node
- 9.4 Open Sky
-
- 10. Links
-
- 10.1 Open
- 10.2 Commercial
-
-
- ______________________________________________________________________
-
- 1. Introduction
-
- 1.1. Introduction
-
- This document wants to explain something about Satellite technology,
- how it works, what do you need, configuration and how to sharing it
- between several clients. Satellite connections are very different from
- terrestrial ones, they require more attention to setup and also some
- more care to maintain them stable (snow or strong rain could prevent
- you to have a good signal).
-
- Feedback are welcome, don't hesitate to contact us:
- berto@fatamorgana.com and flosan@hack-
- it.net .
-
- 1.2. Copyright
-
- Copyright (C) 2000,2001 Roberto Arcomano, Florindo Santoro. This
- document is free; you can redistribute it and/or modify it under the
- terms of the GNU General Public License as published by the Free
- Software Foundation; either version 2 of the License, or (at your
- option) any later version. This document is distributed in the hope
- that it will be useful, but
-
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License for more details. You can get a copy of the GNU
- GPL here
-
- 1.3. Translations
-
- If you want to translate this document you are free, you only have to:
-
-
-
- 1. Check that another version of it doesn't already exist at your
- local LDP
-
- 2. Maintain all 'Introduction' section (including 'Introduction',
- 'Copyright',
-
- Warning! You don't have to translate TXT or HTML file, you have to
- modify LYX file, so that it is possible to convert it all other
- formats (TXT, HTML, RIFF, etc.): to do that you can use "LyX"
- application you download from http://www.lyx.org .
-
- No need to ask me to translate! You just have to let me know (if you
- want) about your translation.
-
- Thank you for your translation!
-
- 1.4. Credits
-
- Thanks to Fatamorgana Computers for
- hardware equipment and experimental opportunity.
-
- Thanks to Linux Documentation Project for
- publishing and uploading my document in a very quickly fashion.
-
- Thanks to Pierre Guiral and Andrei Boros for their help.
-
- 2. Background Knowledge
-
- 2.1. What about satellite
-
- In the last few years satellite began to be applied in Internet
- networking, mainly by medium-big ISPs and we have seen it diffused
- between users. Sat connections are a very different kind of networking
- than terrestrial ones, with different timing such as higher RTT (round
- trip time), but also with different bandwidth value, up to 2 Mbps or
- more.
-
- 2.2. How does it work?
-
- We can imagine a path like this:
-
-
- |||||| S A T E L L I T E ||||||||
- / /|\
- Downl / | Uploading
- load / | from
- to /(4) | (3) server
- client / |
- / |
- SatCard(parabolic antenna) |
- | |
- \|/ |
- USER PC ----make request-----> SAT-SERVER <---retrieving---> INTERNET
- (1) (2)
-
-
-
- So first we make the request (1) (using our Internet connection) to
- the Sat-Server, after it will retrieve out info from Internet (2) and
- it will send it to Satellite (3); in the end we would receive data
- from the it (4) to our home using a parabolic antenna and a Sat Card.
-
- Typically exist 2 kinds of request :
-
-
-
- · Http
-
- · Ftp
-
- Both of them have a little request data and a much bigger answer size,
- so satellite works very well with it, but with a big time of answer,
- this is the biggest problem of satellite connection (consider a
- typical Sat distance, like 36.000 km, so you would have a time access
- of [ 36000 km / 300.000 km/s = 0.120 s = ] 120 ms you have to add (2
- times, cause first ISPs server send it to, then you download it from)
- to classical Internet time access.
-
- Recently ISP allows their clients to use also other kind of service,
- like
-
-
-
- · Chat
-
- · Email
-
- · News
-
- and many others.
-
- There exist also services called "one-way", which consist in mail
- service , download on-demand (where you make a file reservation to be
- scheduled at some time) and site download: these services are offline,
- so you can access to them without modem (or other kind of) connection.
-
- 2.3. Other technologies
-
- We have to report another satellite technology: the 2-way sat
- connection. It uses only the parabolic antenna to contact Internet in
- both 2 directions. Its cost is much higher that 1-way connection. We
- expect something from it for immediate future, for now it allows a
- bandwidth of 4 Mbit/s in download and 256Kbit/s in upload.
-
- 2.4. What is the max bandwidth?
-
- It depends on many factors: ISP purpose, TCP window used, applications
- used by the client and the more important of all, "Internet
- congestion".
-
- You can expect a max bandwidth of 1-4 Mbps and a average of about
- 10-30 KBytes/s, but I repeat, it depends on many factors.
-
- Anyway some ISPs tell you they give you a "Max" bandwidth, while the
- average bandwidth could be very lower, due to intra-ISP congestion.
-
- Some other ISPs guarantees you to have a "Minimal" bandwidth, which is
- more meaningful than "MAX", cause it is available all the time.
-
- Please see Appendix A for more about get downloading performance
- better.
-
- 2.5. How much does it cost?
-
- We have to distinguish between hardware costs and account costs, the
- first are known, while the second depend on which service you choose
- ("guaranteed"/"not guaranteed", what bandwidth).
-
- 2.5.1. Hardware costs
-
- To install our little satellite system we need:
-
- 1. Sat card
-
- 2. Parabolic antenna
-
- 3. one or more feed (converter)
-
- Noticed that we need a digital converter to use Internet via
- satellite.
-
- Sat card costs depends on brand you choose, about 200US$-300US$.
-
- Parabolic antenna is about 50 US$.
-
- Converter is about 50US$.
-
- So we have about 3-400 US$ of hardware cost (maybe you still have to
- add installation cost!!).
-
- If you want also receiver Crypt service:
-
-
- 1. CI is about 100 US$.
-
- 2. CAM is about 100 US$-250 US$.
-
- 2.5.2. Account costs
-
- Here costs depend on what ISPs give you access, what's peak bandwidth,
- if there is a guaranteed bandwidth (which is more important than peak
- one), what kind of service they give you and so on.
-
- Also some ISP gives you free access in change of viewing an always
- foreground spot banner (you cannot iconize it!!): in this case you
- will pay when you'll go to buy something showed in banner!!
-
- Typically account costs are about 100-150 US$ at year for "not
- guaranteed" services and 4-600 US$ or more for guaranteed ones (they
- guarantee you a minimal bandwidth you can use also under congestion
- moments, obviously intra Sat-ISP congestion!! When you go out to
- Internet nobody can guarantee you anything!!).
-
- 2.6. What are the satellites used?
-
- When we speak about satellites we mean: Astra (19.2 degree SE),
- Hotbird (13.2 degree SE), new Europestar (45 degree SE), Eutelsat (8
- degree SW), Astra (26E), ArabSat 3A (26E).
-
- 2.7. What ISPs give Sat Internet Access?
-
- In Europe we know about 8 ISPs giving Sat access for Internet:
-
-
- 1. EuropeOnLine - EON
-
- 2. Netsystem
-
- 3. Starspeeder
-
- 4. Sat Node
-
- 5. Eliosat
-
- 6. Falcon Stream
-
- 7. SkyDSL
-
- 8. OpenSky
-
- 9. DirecPC but this use a proprietary sat
- card (this is a first Sat ISP )
-
- 10.
- http://www.xanticbroadband.com/
-
- EON gives access for about 150 US$ at year without guaranteed
- bandwidth.
-
- Netsystem offers its services at "null cost", you just have to see its
- banner.
-
-
- Starspeeder gives access ???
-
- Eliosat costs 350 US$ at year with a 128 Kbps guaranteed (minimal
- service, see web site for more);in addition it gives 2-way technology
- access for either receive and transmit.
-
- SkyDSL gives access full-time and it costs about 15 US$ at month with
- 128Kbit/s bandwidth, but it allows a bigger bandwidth where you pay
- each Mb downloaded (you can select from 256Kbit/s up to 4Mbit/s), for
- more you can visit its web site.
-
- IMPORTANT : before subscribing some satellite account, please verify
- "foot of Satellite" and diameter of parabola.
-
- OpenSky started before summer 2001 in its "beta test": it allows you
- to try the sat service downloading at maximum 300 MB at month (free).
- To register you need to go at OpenSky registration procedure
- (which is in
- italian language!).
-
- 2.8. What else?
-
- With every kind of DVB card you can also receive TV digital channels
- (free channels only) and some cards have support for common interface
- to watch encrypted channel.
-
- Follows the schema:
-
-
- Smart-Card -> CAM -> Common Interface -> Sat Card (with support C.I.)
-
-
-
- CAM Card (there are many standards used for decryption: SECA, IRDETO,
- VIACCESS and others) is the hardware allowing decryption (for TV,
- Radio and Data) while the Common Interface or C.I. (ETSI EN 50221)
- allow connection between CAM and Sat Card.
-
- 3. Technical Information
-
- 3.1. General working
-
- We now try to understand how satellite connection works and at what
- conditions.
-
- We can imagine a satellite link as a classical Wireless link, I mean a
- link between 2 systems which don't use a real cable to talk each
- other.
-
- Wireless link is very different from Wired link cause we have some
- additional problems to solve, such as reachability, privacy problems
- and so on. Also there could be weather problems, particularly in snow
- or rain conditions.
-
- Anyway, we have to consider the first principle behind Wireless
- communication: line of sight free, which is a MUST unless we are
- unable to talk. For more you can see the Wireless-HOWTO
- .
-
- In sat connections we use a special kind of antenna, a parabolic one,
- that gives us a very high gain in RX, needed to receive satellite
- signal: in fact satellite has a geostational orbital at 36.000 km and
- the only kind of antenna we can use for receiving is just a parabolic
- one.
-
- 3.2. Frequencies
-
- Frequency we receive is from 11GHz up to 12.7 GHz (from the satellite
- transponder, the transmitter sending us datas), a very high freq., but
- the feed (converter in the center of the parabola) converts it to, in
- output, 1-2 GHz so that we'll able to send signal to the receiver
- through the cable (up to 40m depending to cable loss).
-
- 3.3. DVB Receiver Card
-
-
-
- 1 GHz Signal --> |RX|--> |ADC| --> |Low Level Network| --> |O.S. TCP/IP Stack|--> Data
- |____________________________________|
- DVB Card
-
-
-
- Now we can imagine a classical RX at 1 GHz receiving analog signals
- from the Sat, converting it to digital signals and giving all to the
- low level network layer (ISO OSI 1,2): here, card firmware builds a 2
- level packet (pretty like ethernet) to be sent to our PC with Linux,
- Windows, or other system, and in the end, we will only have to
- transform it to a TCP/IP packet.
-
- 3.4. Data Link Level DVB setting
-
- Here we have to config some settings, directly to the DVB card:
-
-
- 1. Frequency working, we have to set the satellite frequency (as from
- magazines): it is between 11.8 GHz and 12.8 GHz for example
- 12640000 KHz
-
- 2. Symbol rate, measured in symbols per seconds, typically 22 MS/s
- (Mega Symbols per seconds)
-
- 3. Polarization, which is an antenna setting configurable in software:
- possible values are H (Horizontal) or V (Vertical).
-
- 4. PIDs. The PID is used for select a trasmission between many signal
- from same frequency.
-
- 5. Also we have to specify the bitfilter mask, which tells us how
- large is the destination MAC addresses group (bitfilter mask is
- similar to TCP/IP netmask, the only difference is that the
- bitfilter mask is 48 bit size while TCP/IP netmask is 32 bit size).
- Always Internet data is sent with Unicast PID, while Video always
- is sent using Multicast PID .
-
- 6. Calculate MAC address: here we specify what will be our MAC address
- (for our DVB card). You need to do this cause some ISP uses an
- algorithm (see Appendix A for more) which calculates your MAC
- address from your IP address, some other ISP uses your own MAC
- address.
-
- 3.5. TCP/IP working
-
- As we said in 2.2 section, first we have to make a request using the
- modem interface (i.e. ppp0 or whatever we use to reach Internet), then
- the answer will return to our DVB interface (dvb0).
-
- Modern O.S. allow us to receive packets from an input interface,
- different from the output interface from where we made the request: to
- do it we have to "disable" some packets flow control, such as type an
-
- echo "0" > /proc/sys/net/ipv4/conf/dvb0/rp_filter (for Linux).
-
- 3.6. Authentication
-
- It remains only one thing to complete our description: authentication
- method.
-
- Some Sat ISPs use the so called "Proxy Authentication": when you used
- their proxy, you also need to give login and password to continue the
- request (you should have been subscribed some kind of account to use
- their sat service): once done, the ISP use your IP address to
- calculate your MAC address (see Appendix A for more), to which send
- the answer.
-
- Some other ISPs require you make a VPN connection (using your login
- and password) first, then they will control your registration account
- (where they retrieve your MAC address) and will send data directly to
- (and only to) your card (your MAC address).
-
- Anyway noticed that you can modify your dvb sat filter value to be
- able to receive packets destined to EVERY mac address (related to a
- single frequency).
-
- 3.7. Services I can use with a sat connection
-
- Typically services you can have from sat connections depend on what
- authentication system is used by ISP:
-
-
- · with classical "Proxy Authentication" you can only use HTTP and FTP
- service, while
-
- · with VPN connection you have (ideally) no limit to services you can
- use, the only limit is decided by RTT (time access) to satellite,
- about 500-1000 ms average: so you can forget to use "Voice" or
- other "Real Time" services!! (see VoIP-HOWTO
- for more). Anyway you still
- can use: mail, chat, telnet, ping, dns and so on.
-
- 4. Requirements
-
- Here we will see what we need to try a Sat system.
-
- 4.1. Knowledge requirement
-
- For this trying you need some experience in internetworking under
- Linux (as from Net-HOWTO ) and a very little of practical experience with
- parabolic antenna and sat systems (you should be able to pointing out
- your antenna, with right angles).
-
-
- 4.2. Hardware
-
- We need:
-
-
- 1. Parabolic antenna, also taken from an analog system.
-
- 2. Digital converter to be placed in the middle of the antenna.
-
- 3. Receiver card DVB compatible.
-
- 4. a PC to connect to.
-
- 4.3. Software
-
- Here you need a
-
-
- 1. driver for the DVB card working under your O.S. (Linux, Windows or
- other).
-
- 2. right setting to use it
-
- 3. external application in some cases (such as VPN-PPTP client for ISP
- like Netsystem or Starspeeder).
-
- For the software under Linux you can found the Siemens DVB driver at
- Linux TV Project .
-
- 4.4. TV Software
-
- There is also some Video software used to implement TV reception:
-
- 4.4.1. Under Windows
-
-
- 1. MultiDec MultiDec 6.6b
- (free with source
- code)
-
- 2. TPREdit TPREdit (for Technotrend)
-
- 3. WinTV DVBs Hauppauge or
- Technotrend (for Siemens compatible
- card, Hauppauge, Technotrend, Technisat, etc... )
-
- 4. WinDVB2000 WinDVB2000 (about
- 19$).
-
- 4.4.2. Under Linux
-
-
- 1. gVideo is an application included in Siemens driver
-
- 2. Vdr Video Recoder (good for watch TV)
-
- 5. Base setup
-
- 5.1. First: mounting
-
- The first thing we have to do is to mount our parabolic antenna;
-
- After we need to pointing it out (searching right degrees from some
- magazine): degrees are always intended from south to east or to west
- for horizontal one and from ground to satellite line for vertical one.
- Classical pointing tools is the compass.
- 5.2. Calibrating
-
- How can we see if we are right oriented?
-
- After decided a right range of angles, we have to adjust it measuring
- power level. For such a thing we can
-
-
- 1. Use for example an analog receiver (which is compatible with
- digital converter) and start to search right degree: when we see
- some imagine we'll get it. I suggest to use analog converter cause,
- maybe, you have one (from precedent installation) and cause it is
- more simple to calibrate it than digital one.
-
- 2. Use a power meter (about 20US$) with sequential lights: at full
- signal all lights turn up.
-
- 5.3. Double Feed
-
- You can also install a double feed system (some vendors sell a
- complete kit with standard distance to receive, for example, Astra
- (19.2 SE) with Eutelsat (16 SE) or with HotBird (13 SE).
-
- For mounting it you have to consider, in addition, that satellite is
- at the opposite side of the converter, like in figure:
-
-
- SAT1 SAT2
- \ /
- \ /
- \ C1 C2 /
- \ \ \ / / /
- \ \ / \ / /
- \____\ /___\ /_____/
-
- Top View
-
- C1 receives from SAT2
- C2 receives from SAT1
-
-
-
- Also, with 2 focus, you would use a diseq.
-
- 5.4. Data-link level adjusting
-
- Once we got analog signal we have to adjust our receiver to right
- frequency, PID, speed rate and so on.
-
- I report here an example of configuration, for EON (EuropeOnLine),
- transponder 114 on Astra satellite (19.2 SE)
-
- Frequency: 12640 MHz
-
- Polarization: V (Vertical)
-
- Symbol Rate: 22000 KS/s
-
- PIDs:
-
-
- · Unicast: 512 (decimal), 0x200 (hexadecimal)
-
- · Multicast: 785, 786, 1041 (decimal), 0x311, 0x312, 0x411
- (hexadecimal), but you should notice that, in many cases, Multicast
- PIDs are taken in automatic.
- We also need another info: what MAC address to assign to our DVB card.
-
-
- Again, for EON you can see Appendix A to calculate MAC address from
- dynamic IP address.
-
- Obviously you need login and password to use ISP service.
-
- 6. Configuration under Linux
-
- In this section I will assume to use a Siemens compatible card, like
- an Hauppage WinTV DVB card, for such cards you can download drivers
- from LinuxTV or DVB-s PCI cards
- under Linux .
-
- Unfortunately there are no drivers (at this moment) for SkyStar2
- (Netsystem card) for Linux!
-
- 6.1. Drivers installation
-
- Once downloaded drivers, you have to untar them to a directory, enter
- it and type "make" and "make insmod". To do this you need to have
- actual kernel sources under /usr/src/linux (unless, download them from
- http://www.kernel.org and recompile them).
-
- After made "make insmod", your system should have DVB modules loaded.
- To unload them type simply "make rmmod".
-
- 6.2. Setting up /etc/dvbd.conf
-
- /etc/dvbd.conf file is used to setup data-link parameters for your DVB
- card. Here main settings:
-
-
- · "power", which indicates the power to LNB, 1=ON, 0=OFF. Usually you
- should set it to 1, unless you do some kind of cascade between more
- than 1 LNB.
-
- · "symbolrate", this is the symbol rate per seconds, for example
- 22.000.000.
-
- · "frequency", at which receiving datas, like 12.640.000.
-
- · "ttk", the 22 kHz signal, almost always to 1.
-
- · "diseqc", used to control the diseq, (it means only when you have a
- diseq controlling 2 or more converters) 0 if none.
-
- · "AFC", usually set to 1.
-
- · "polarization", 1 for horizontal or 0 for vertical one.
-
- · "filter_n ", where n is intended 0 for
- Unicast and 1-9 for Multicast; PID is expressed in decimal form,
- MAC is the MAC address only valid for Multicast filter and
- BITFILTER is a number which bits represent bytes to mask (for
- example 10 = 2 (bit 1) + 8 (bit 3), so mask will be 00 00 FF 00 FF
- 00).
-
-
- Example
-
-
- ------------------------------------------
-
-
- # DVB receiver configuration file, (c) 2000 data planet international
-
- # standard location in /etc
-
- # LNB power on=1/off=0
-
- power 1
-
- # symbol rate [symbol/sec]
-
- symbolrate 22000000
-
- # ASTRA TR 114
-
- frequency 12640000
-
- # 22 kHz signal on=1/off=0
-
- ttk 1
-
- # diseqc on=1/off=0
-
- diseqc 0
-
- # AFC on=1/off=0
-
- AFC 1
-
- # polarisation H=1/V=0
-
- polarisation 1
-
- # settings for MPE filter, PID and MAC filtering, valid MAC bytes
-
- filter_0 512
-
- filter_1 785 00:D0:5C:1E:96:01 48
-
- filter_2 786 00:D0:5C:1E:96:01 48
-
- filter_3 1041 00:D0:5C:1E:96:01 48
-
- -----------------------------------------
-
- filter_0 has no MAC and no bitfilter values cause the right MAC
- address is calculated from IP address (see Appendix A). We will see
- this setting is OK only for some ISP, for others we'll have to change
- dvbd.c
-
- 6.3. Dvbd daemon
-
- Once your /etc/dvbd.conf is ok, you can launch dvbd application,
- which, if executed without -d option, write to stdout signal quality
- level:
-
-
- · Sync MUST be 127 or near it
-
- · Vber MUST be 0
-
- unless you are not well receiving from Sat (check cable and/or dish
- pointing).
-
- Note:
-
-
- Maybe you have to change, in dvbd.h this line
-
- #define network_device "eth0"
-
- to
-
- #define network_device "ppp0"
-
- depending on which interface you use to reach Internet, eth0 or ppp0:
- type "make" to update binary file and restart dvbd.
-
- 6.4. How to config EON service
-
- Now you have a good signal, you can try to use some sat service.
-
- For EON go at "proxy" setting in Netscape preferences and set under
- HTTP and FTP:
-
- proxy.xxx.europeonline.net
-
- and, in "port" 8080 and FTP proxy with "port" 8090.
-
- where xxx is the transponder number (103,113,114 or 115) you are using
- (see Appendix B for more).
-
- Now you should be able to navigate wherever you want.... Good
- navigation.
-
- To share EON service with many clients you can use Squid proxy
- application, enabling cascade to EON
- proxy.
-
- For a more complex use of EON, like more complex cascade proxy or
- sharing users, see EON Linux Masquering FAQ Page
-
-
- 6.5. How to use Netsystem service
-
- Netsystem service is a little more complicated than EON under Linux,
- cause, in addition, you need to setup:
-
-
- 1. VPN connection
-
- 2. patch for pppd (needed only if using pppd <= 2.4.0)
-
- 3. routing settings with simple scripts
-
- 4. patch for dvbd.c
-
- 5. Test it
-
- 6. Get performance better
-
- 7. Sharing Netsystem with many clients
-
- 6.5.1. VPN connection
-
- First you need to download VPN PPTP client application
- .
-
- After untared, compiled and installed it, you should add an entry to
- your /etc/ppp/pap-secrets and /etc/ppp/chap-secrets files, like that:
-
- "login" * "password" *
-
- where "login" and "password" are the same according to Netsystem
- registration .
-
- 6.5.2. Patch for pppd
-
- As described at PPTP description
- , you need to patch your
- pppd daemon to support connection with Netsystem VPN server (Linux
- server).
-
- Warning: using pppd version >= 2.4.0 you don't need pppd patch.
-
- So you have to:
-
-
- 1. download a recent pppd version
-
-
- 2. download and gunzip the correspondent patch for pppd from Here
-
-
- 3. untar pppd in a directory
-
- 4. type "patch -p0 < patch_name"
-
- 5. enter pppd directory
-
- 6. type "make", "make install"
-
- 6.5.3. Routing settings
-
- Now your pppd will be able to working with:
-
- "pptp vpn.netsystem.com debug user "
-
- where is your login account from Netsystem: you should see, in
- log file (/var/log/messages) ppp1 connection debug info.
-
- If all is ok you should see ppp1 interface with "ifconfig" command.
-
- If you still have problems on authentication, please add a "noauth"
- line to your /etc/ppp/options file.
-
- Once ppp1 interface is up, you should do the following:
-
-
- 1. type "ifconfig ppp1" and find the IP address (I will call IP) on
- the right of "P-t-P:" string.
-
- 2. delete it from routing table with "route del IP"
-
- 3. add it to ppp0 interface with "route add IP dev ppp0"
-
- 4. delete default gateway from ppp0 with "route del default"
-
- 5. add default gateway to ppp1 with "route add default dev ppp1"
-
- Points 1-3 are requested cause point-to-point interface are managed,
- under Linux, adding the gateway to the new interface (which is not a
- good idea in this case): unless it you will have a endless loop, cause
- your packet will be continuously encapsulated on itself.
-
- Points 4,5 are used to make "all internet requests" to ppp1 interface,
- so we'll reach the "world" by using VPN connection: this could be not
- optimal in some condition, for example for DNS queries, which could be
- sent directly to avoid useless Sat delay time.
- Instead of manually setup routing configuration you can try using
- these little scripts:
-
- "netsystem.on" script
-
- ______________________________________________________________________
-
-
- route add IP_DNS1 dev ppp0
-
- route add IP_DNS2 dev ppp0
-
- route add -net 212.31.242.0 netmask 255.255.255.0 dev ppp0
-
- pptp vpn.netsystem.com user
-
- /bin/sleep 5
-
- route add default dev ppp1
-
- ______________________________________________________________________
-
-
- "netsystem.off" script
-
- ______________________________________________________________________
-
-
- route del IP_DNS1 dev ppp0
-
- route del IP_DNS2 dev ppp0
-
- route del -net 212.31.242.0 netmask 255.255.255.0 dev ppp0
-
- kill -9 `ps x|grep "pppd"|grep ""|grep -v "ps"|tr " " "\n"|head
- -n 2`
-
- rm --force /var/lock/LCK..tty*
-
- rm --force /var/run/pptp/*
-
- rm --force /var/run/ppp1.pid
-
- killall -9 pptp
-
- ______________________________________________________________________
-
-
- IP_DNS1 and IP_DNS2 are ip addresses of your dns servers (primary and
- secondary).
-
-
- is the login name of your Netsystem account.
-
- I tried it out under kernel 2.4.6 RedHat 7.1 and it works very well
- (without any problems about ppp1 endless loop or similar).
-
- This line:
-
- kill -9 `ps x|grep "pppd"|grep ""|grep -v "ps"|tr " " "\n"|head
- -n 2`
-
- is used to find PID of pppd process talking with VPN server (ppp1
- interface): notice that you cannot just only type " killall pppd"
- cause your ppp0 interface also would go down.
-
- 6.5.4. Patch for dvbd.c
-
- After solved problems about PPTP you have to change some line in
- dvbd.c, near the end of it:
-
-
- if (strcmp (v, "filter_0") == 0) { if (s != NULL) { unsigned char ip[4];
- dvbcfg[0].status = ON ;
- dvbcfg[0].filter.data[0] = 0x3eff ;
- dvbcfg[0].filter.pid = (__u16) atoi (s) ;
- dvbcfg[0].filter.mode = 0x0c ;
- if (ipget (ip, network_device)) { fprintf(stderr,"Can't get local ip address. Stop.\n") ; return -1 ; }
- syslog (LOG_NOTICE, "Local ip is %u:%u:%u:%u\n", ip[0], ip[1], ip[2], ip[3]);
- dvbcfg[0].filter.data[1] = (ip[3] << 8) | 0x00ff ;
- dvbcfg[0].filter.data[2] = (ip[2] << 8) | 0x00ff ;
- dvbcfg[0].filter.data[6] = (ip[1] << 8) | 0x00ff ;
- dvbcfg[0].filter.data[7] = (ip[0] << 8) | 0x00ff ;
- dvbcfg[0].filter.data[8] = (0x02 << 8) | 0x00ff ;
- dvbcfg[0].filter.data[9] = (0x00 << 8) | 0x00ff ;
- setmac (ip) ; }
- else { dvbcfg[1].status = OFF ; } }
-
-
-
- Now following lines:
-
-
- dvbcfg[0].filter.data[1] = (ip[3] << 8) | 0x00ff ;
-
- dvbcfg[0].filter.data[2] = (ip[2] << 8) | 0x00ff ;
-
- dvbcfg[0].filter.data[6] = (ip[1] << 8) | 0x00ff ;
-
- dvbcfg[0].filter.data[7] = (ip[0] << 8) | 0x00ff ;
-
- dvbcfg[0].filter.data[8] = (0x02 << 8) | 0x00ff ;
-
- dvbcfg[0].filter.data[9] = (0x00 << 8) | 0x00ff ;
-
-
- will be changed to
-
-
- dvbcfg[0].filter.data[1] = (MAC[5] << 8) | 0x00ff ;
-
- dvbcfg[0].filter.data[2] = (MAC[4] << 8) | 0x00ff;
-
- dvbcfg[0].filter.data[6] = (MAC[3] << 8) | 0x00ff ;
-
- dvbcfg[0].filter.data[7] = (MAC[2] << 8) | 0x00ff ;
-
- dvbcfg[0].filter.data[8] = (MAC[1] << 8) | 0x00ff ;
-
- dvbcfg[0].filter.data[9] = (MAC[0] << 8) | 0x00ff ;
-
- Where MAC[0]:MAC[1]:MAC[2]:MAC[3]:MAC[4]:MAC[5] is our MAC address
- (according to Netsystem registration).
-
- For example, using the address 00:d0:d0:d0:d0:d0 we'll have:
-
- dvbcfg[0].filter.data[1] = (0xd0 << 8) | 0x00ff ;
-
- dvbcfg[0].filter.data[2] = (0xd0 << 8) | 0x00ff;
-
-
- dvbcfg[0].filter.data[6] = (0xd0 << 8) | 0x00ff ;
-
- dvbcfg[0].filter.data[7] = (0xd0 << 8) | 0x00ff ;
-
- dvbcfg[0].filter.data[8] = (0xd0 << 8) | 0x00ff ;
-
- dvbcfg[0].filter.data[9] = (0x00 << 8) | 0x00ff ;
-
- notice hexadecimal notation 0x??
-
- After, you have to type "make" and use the new dvbd created.
-
- Note: to successfully patch the dvbd.c you need to use dvb driver
- version >= 0.8.2, cause older versions have some instability problems.
-
- 6.5.5. Test it
-
- Finally, we can test Netsystem under Linux. We can make a "ping
- www.somehostpingable.com" and check the response time: it should be
- between 400 and 2000 ms.
-
- If you still have problems, you should control if all is OK with VPN
- interface:
-
-
- 1. open your preferred network sniffer (for example Ethereal
- ) and starts to analyze "ppp0" interface
- (ppp0, not ppp1!!)
-
- 2. make a ping
-
- If VPN is ok you should see 2 (or maybe 1) GRE-Encapsulated packets
- each second, endless. If you cannot view anything your VPN is not
- correctly working: stop it and restart it.
-
- 6.5.6. Get performance better
-
- Once you setup all things you NEED to use (particularly with Netsystem
- service) some "download accelerator" to get performance better: please
- see Appendix A for more.
-
- 6.5.7. Sharing Netsystem with many clients
-
- To do this you can enable "IP Masquering", allowing your client to use
- VPN like a normal Internet interface; main problem is that our
- satellite connection is very good for download while it has bad
- performance for just browsing web pages (or other service more
- interactive than downloading).
-
- You can think to use Squid proxy or Socks
- proxy , but you don't solve your problems,
- cause even now ALL your request would be forwarded to same interface,
- VPN.
-
- The solution is to use 2 routing tables, one using direct line
- interface and the other using VPN one. So you can do like this:
-
-
- 1. be sure of have installed "iproute2" commands (for example type
- "ip" on shell and control if it tells you something), for more see
- Linux 2.4 Advanced Routing HOWTO
- .
-
- 2. be sure of have started Netsystem service and annotate ppp1
- interface IP address, we'll call it LOCALIP.
-
- 3. type: "echo "210 sat" >> /etc/iproute2/rt_tables", to more
- comfortable call "sat" rule 210
-
- 4. type: "ip rule add from LOCALIP table sat", to create table "sat"
- relative to all requests coming from LOCALIP IP address.
-
- 5. type: "ip route add default dev ppp1 table sat", to send all "sat"
- requests (see above) to ppp1 interface.
-
- 6. if you use Socks proxy be sure to set,
- in sockd.conf file, "external" to LOCALIP.
-
- 7. if you use Squid proxy be sure to set,
- in squid.conf file, "tcp_outgoing_address" to LOCALIP.
-
- Once done all that, you will notice to have 2 kind of working: without
- any proxy your clients will ask to direct line, while by using proxy
- (squid or sockd) the request will be forwarded to VPN interface and,
- definitely, toward satellite.
-
- Notice that maybe you wish to use sockd instead of squid, cause
- satellite requests are typically used for download (while squid is
- typically used for browsing...).
-
- What happens with iproute2 commands is that, when you ask for an
- address to sockd or squid, relative proxy (using IPLOCAL IP address,
- bound at run-time by proxy network daemon) request enters the TCP/IP
- stack where kernel will forward it (thanks to point 4 above) to sat
- table and, definitely (by using point 5) to ppp1 interface. All other
- rules will be forwarded to classical default route (I mean across ppp0
- interface or whatever other interface for direct Internet).
-
- 6.6. How to use Sat Node service
-
- You have to follow all instructions as for Netsystem.
-
- Before enabling VPN connection, you need to type:
-
-
- ·
-
- · vpn server just through ppp0
-
- ·
-
- · to reach every place.
-
- What really changes from Netsystem is that, we don't force VPN gateway
- (212.56.224.34, IP on the right of ''P-t-P'' in ppp1 interface) on
- ppp0 interface, but we force another IP (212.56.224.36). All other
- things should not change.
-
- Thanks to Ricardo Santiago Mozos and Norberto Garcia Prieto.
-
- 6.7. OpenSky service under Linux
-
-
- 1. You need to register at Opensky Registration site
- . You'll
- receive a confirming email with login and password in few days.
-
- 2. After you have to go to https://sdr.eutelsat.net
- and enter login and password data to
- connect.
-
-
- 3. Set the proxy: ''proxy.eutelsat.net:8080''.
-
- It is strongly suggested to use downloader applications (see Appendix
- A for more) to get performance better.
-
- OpenSky is the latest satellite service and it offers 300 MB at month
- (for free).
-
- Configuration is pretty like EON service, you have to use 0.8.2
- siemens drivers you download from LinuxTV
- , then you NEED to patch dvbd
- applications.
-
- To apply the patch and to test OpenSky you can find useful infos at:
-
-
- · http://members.tripod.com/andrei_b/linux/dvbd/dvb-app-dvbd.htm
-
-
- · http://pguiral.free.fr/DVBS/opensky.html
- .
-
- 7. Configuration under Windows
-
- 7.1. EON
-
- Hauppage WinTV has DVB-DATA application that allows to specify data-
- link settings.
-
- 7.2. Netsystem
-
- First you need to install VPN capabilities.
-
- In addition you need to download Netsystem software (always foreground
- spot banner) and launch it: after you should not be able to use
- Netsystem service: you can download it from here
-
-
- 7.3. OpenSky
-
- See Linux.
-
- 8. Appendix A - Notes
-
- 8.1. Translation Dynamic IP -> MAC Address
-
- The translation used by some ISPs to calculate MAC address (which need
- to have your DVB card to receive their packets) is:
-
- 00 : 01 : IP[0] : IP[1] : IP[2] : IP[3]
-
- where
-
- IP[0].IP[1].IP[2].IP[3] is your dynamic IP address.
-
- This feature is used, for example, by EON.
-
- 8.2. TCP Window
-
- Satellite connections are an interesting example of very high RTT
- (round trip time, access time): another example is the Mars - Earth
- communication or also the Moon - Earth one.
-
- These connections have a very bad feature: very low interactively.
-
-
- Typical network (or digital, generally) connections use the so called
- transmission "window", which represents the data buffer can be sent
- before waiting for an answer. In TCP/IP protocol stack this is the TCP
- Window.
-
-
- ----------------------
- | - - - - - - - > can continue |-|-|-|---->
- | ----------------------
- | Buffer sendable before confirm
- |
- | - - - - - - - <----------------------
- Confirmation Answering
-
-
-
- Now, if our communication has an high access time and if we had a
- little TCP Window we would lose very much time only waiting for the
- data confirmation (ACK), so the real bandwidth would decrease (for
- example if you have a 16KB TCP window, typical of Windows systems and
- a RTT of 400 ms, you cannot overcome 16KB/0.4 = 40 KB/s)
-
- Solution is to use a very high TCP Window (such as 256 KB or some MB).
-
- Unfortunately, under many systems, is not so simple to have a great
- TCP Window, so, in latest years, it starts to appear new applications
- ("download accelerators" described in next section) that split in many
- pieces a file and download all them in the main time: this is just
- equivalent to download only one file with a single piece size,
- avoiding the RTT problem.
-
- 8.3. Download accelerator
-
- We report here some useful link to so called "download accelerator"
- which is an application that does 2 things:
-
-
- 1. resuming session management, it allows stopping downloading and
- restarting later (this can be done thanks to "resuming feature"
- introduced in Http and Ftp server, which allows you to specify at
- what byte number start to download).
-
- 2. splitting, divide the file in many pieces and let them start in a
- multithreaded fashion.
-
- As we saw in the previous section, a download accelerator allows us to
- increase satellite bandwidth.
-
- 8.3.1. Under Linux
-
-
- · Aria
-
- 8.3.2. Under Windows
-
-
- · FlashGet
-
- · GetRight
-
- · Mass Downloader
-
- 9. Appendix B - Well Known Sat ISP setting value
-
-
-
- 9.1. EuropeOnLine
-
- EON sends data from Astra satellite (19.2 SE).
-
- MAC address is calculated from IP address (see Appendix A).
-
- It uses "Proxy Authentication".
-
- Follows the 4 transponder setting:
-
- 9.1.1. Transponder 113
-
-
- · Frequency: 12633.250 MHz,
-
- · SRate : 22 MS/s
-
- · Polarization: Horizontal
-
- · Unicast PID: 512 (decimal)
-
- 9.1.2. Transponder 114
-
-
- · Frequency: 12640 MHz,
-
- · SRate : 22 MS/s
-
- · Polarization: Vertical
-
- · Unicast PID: 512 (decimal)
-
- 9.1.3. Transponder 115
-
-
- · Frequency: 12662.750 MHz,
-
- · SRate : 22 MS/s
-
- · Polarization: Horizontal
-
- · Unicast PID: 512 (decimal)
-
- 9.1.4. Transponder 103
-
-
- · Frequency: 12461 MHz,
-
- · SRate : 27.5 MS/s
-
- · Polarization: Horizontal
-
- · Unicast PID: 512 (decimal)
-
- 9.2. Netsystem
-
- Netsystem uses Astra satellite (19.2 SE) to send data .
-
- MAC address used is your real MAC address DVB card.
-
- It uses VPN connection.
-
- Follows data setting:
-
-
-
- 9.2.1. Transponder 119
-
-
- · Frequency: 12721 MHz
-
- · SRate: 22MS/s
-
- · Polarization: Horizontal
-
- · Unicast PID: 451 (decimal)
-
- 9.3. Sat Node
-
- Sat Node uses Astra satellite (19.2 SE).
-
-
- · Frequency: 12603.750 MHz
-
- · SRate: 22MS/s
-
- · Polarization: Horizontal
-
- · Unicast PID: 302
-
- 9.4. Open Sky
-
- Open sky uses Eutelsat satellite (7 SE).
-
-
- · Frequency: 11262 MHz
-
- · SRate: 27.5MS/s
-
- · Polarization: Horizontal
-
- · Unicast PID: 3003
10. Links
@@ -1471,7 +44,6 @@
OpenSky
-
DirecPC
http://www.xanticbroadband.com/
diff --git a/LDP/guide/docbook/Linux-Networking/Text-Terminal.xml b/LDP/guide/docbook/Linux-Networking/Text-Terminal.xml
deleted file mode 100644
index 916da206..00000000
--- a/LDP/guide/docbook/Linux-Networking/Text-Terminal.xml
+++ /dev/null
@@ -1,8535 +0,0 @@
- Text-Terminal-HOWTO
- David S. Lawyer
- v1.36, August 2004
-
- This document explains what text terminals are, how they work, how to
- install and configure them, and provides some info on how to repair
- them. If you don't have a terminal manual, it may be of help. While
- it's written for real terminals on a Linux system, much of it is also
- applicable to terminal emulation and may be helpful for non-Linux sys
- tems.
- ______________________________________________________________________
-
- Table of Contents
-
-
-
- 1. Introduction
-
- 1.1 Copyright, Trademarks, Disclaimer, & Credits
- 1.1.1 Copyright
- 1.1.2 Disclaimer
- 1.1.3 Trademarks.
- 1.1.4 Credits
- 1.2 Future Plans: You Can Help
- 1.3 New Versions of this HOWTO
- 1.4 New in Recent Versions:
- 1.5 Related HOWTOs, etc.
- 1.6 Terminology Used in this Document
- 1.7 What is a Terminal ?
-
- 2. Types of Terminals
-
- 2.1 Dumb Terminals
- 2.2 Text Terminals
- 2.3 Graphic GUI Capabilities of Text Terminals
- 2.3.1 Graphics GUI displays
- 2.4 Thin Clients (Terminals ?)
- 2.4.1 Introduction
- 2.4.2 MS Window terminals
- 2.4.3 Network computers (NCs)
- 2.4.4 Thin clients and NCs under Linux
- 2.4.5 Hardware hookups
- 2.4.6 History and the future
- 2.5 Emulation on a PC
-
- 3. Quick Install
-
- 4. Why Use a Terminal ?
-
- 4.1 Intro to Why Use a Terminal
- 4.2 Lower Hardware Costs ?
- 4.3 Control of Software
- 4.4 Hardware Upgrades
- 4.5 Other Advantages of Terminals
- 4.6 Major Disadvantages of Terminals
- 4.7 Are Text Terminals Obsolete ?
-
- 5. Overview of How Terminals Work (in Linux)
-
- 5.1 Device Names
- 5.2 Login/Logout
- 5.3 Half/Full Duplex
- 5.4 Terminal Memory
- 5.5 Commands for the Terminal
- 5.6 Lack of Standardization Solved by Terminfo
- 5.7 The Interface
- 5.8 Emulation
- 5.9 The Console
-
- 6. Terminal Special Files such as /dev/tty
-
- 6.1 Serial Port Terminals
- 6.2 Pseudo Terminals
- 6.3 The Controlling Terminal /dev/tty
- 6.4 /dev/ttyIN "Terminals"
- 6.5 The Console: ttyN or vc/N
- 6.6 Creating a Device with "mknod"
-
- 7. Some Details on How Terminals Work
-
- 7.1 Terminal Memory Details
- 7.2 Early Terminals
- 7.3 Escape Sequences and Control Codes (intro)
- 7.3.1 Control codes
- 7.3.2 Escape sequences
- 7.4 Display Attributes & Magic Cookies
-
- 8. Special Features of Some Terminals
-
- 8.1 Color
- 8.2 Multiple Sessions
- 8.3 Printer/Auxiliary Port
- 8.4 Pages
- 8.5 Character-Sets
- 8.5.1 Graphics (Line Drawing, etc.)
- 8.5.2 National Replacement Characters (obsolete)
- 8.6 Fonts
- 8.7 Keyboards & Special Keys
- 8.8 Mouse
-
- 9. Terminal Emulation (including the Console)
-
- 9.1 Intro to Terminal Emulation
- 9.2 Don't Try to Use TERM Variable for Emulation
- 9.3 Communication (Dialing) programs
- 9.3.1 Emulation under X Window
- 9.3.2 Real terminals better
- 9.4 Testing Terminal Emulation
- 9.5 The Linux Console
- 9.6 Emulation Software
- 9.6.1 Make a Linux PC a terminal
- 9.6.2 Make a non-Linux PC a terminal
-
- 10. Flow Control (Handshaking)
-
- 10.1 Why Is Flow Control Needed ?
- 10.2 Padding
- 10.3 Overrunning a Serial Port
- 10.4 Stop Sending
- 10.5 Keyboard Lock
- 10.6 Resume Sending
- 10.7 Hardware Flow Control (RTS/CTS etc.)
- 10.7.1 RTS/CTS, DTR, and DTR/DSR Flow Control
- 10.7.2 Connecting up DTR or DTR/DSR Flow Control
- 10.7.3 Old RTS/CTS handshaking is different
- 10.7.4 Reverse Channel
- 10.8 Is Hardware Flow Control Done by Hardware ?
- 10.9 Obsolete ?? ETX/ACK or ENQ/ACK Flow Control
-
- 11. Physical Connection
-
- 11.1 Introduction
- 11.2 Multiport I/O Cards (Adapters)
- 11.3 Direct Serial Cable Connection.
- 11.3.1 Pin numbering
- 11.3.2 Null Modem cable pin-out (3, 4, or 5 conductor)
- 11.3.3 Standard Null Modem cable pin-out (7 conductor)
- 11.3.4 Overcoming length limitations
- 11.3.5 Hardware Flow Control cables
- 11.3.6 Cable tips
- 11.3.7 A kludge using twisted-pair cable
- 11.3.8 Cable grounding
- 11.4 Modem Connection
- 11.4.1 Dialing out from a terminal
- 11.4.2 Terminal gets dialed into
- 11.5 Telnet
- 11.6 Terminal Server Connection
- 11.6.1 What is a terminal server ?
- 11.6.2 Evolution of the "terminal server"
- 11.7 Connector and Adapter Types
- 11.7.1 Sex of connector/adapters
- 11.7.2 Types of adapters
- 11.7.3 DB connectors
- 11.7.4 RJ modular connectors
- 11.7.4.1 6-conductors: RJ11/14, RJ12, and MMJ
- 11.7.4.2 8-conductors and 10-conductors
- 11.8 Making or Modifying a Cable
- 11.8.1 Buy or make ?
- 11.8.2 Pin numbers of 9 and 25 pin connectors
- 11.8.3 Installing DB connectors on cable ends
- 11.8.4 Installing RJ connectors
-
- 12. Set-Up (Configure) in General
-
- 12.1 Intro to Set-Up
- 12.2 Terminal Set-Up (Configure) Overview
- 12.3 Computer Set-Up (Configure) Overview
- 12.4 Many Options
- 12.5 Communication Interface Options
- 12.5.1 Speed
- 12.5.2 Parity & should you use it ?
- 12.5.3 Bits/Character
- 12.5.4 Which Flow Control (Handshaking) ?
- 12.5.5 Port select
- 12.6 Quick Attempt
-
- 13. Terminal Set-Up (Configure) Details
-
- 13.1 Send Escape Sequences to the Terminal
- 13.2 Older Terminals Set-Up
- 13.3 Getting Into Set-Up (Configuration) Mode
- 13.4 Communication Options
- 13.5 Saving the Set-up
- 13.6 Set-Up Options/Parameters
- 13.7 Emulation {Personality} {{Terminal Modes}}
- 13.8 Display Options
- 13.8.1 Character Cell Size {Char Cell}
- 13.8.2 Columns/Lines
- 13.8.3 Cursor
- 13.8.4 Display Attributes (Magic Cookies)
- 13.8.5 Display Control Characters {Monitor}
- 13.8.6 Double Width/Height
- 13.8.7 Reverse Video {Display} (Background Light/Dark)
- 13.8.8 Status Line
- 13.8.9 Upon 80/132 Change: Clear or Preserve?
- 13.9 Page Related Options
- 13.9.1 Page Size
- 13.9.2 Coupling (of cursor & display)
- 13.10 Reporting and Answerback
- 13.10.1 Answerback Message (String)
- 13.10.2 Auto Answerback
- 13.10.3 Answerback Concealed
- 13.10.4 Terminal ID {ANSI ID}
- 13.11 Keyboard Options
- 13.11.1 Keyclick
- 13.11.2 Caps Lock {Keylock}
- 13.11.3 Auto Repeat {Repeat}
- 13.11.4 Margin Bell
- 13.11.5 Remapping the Keys
- 13.11.6 Corner Key (for Wyse only)
- 13.11.7 Numeric Keypad or Arrow Keys Sends
- 13.11.8 What does shifted-del and shifted-bs send?
- 13.11.9 PC Scan Codes
- 13.11.10 Alternate Characters
- 13.12 Meaning of Received Control Codes
- 13.12.1 Auto New Line {Newline}
- 13.12.2 Auto Line Feed {Rcv CR}
- 13.12.3 Recognize Del (Wyse Only ??) or Null
- 13.13 Where New Text Goes
- 13.13.1 Line Wrap
- 13.13.2 Scrolling
- 13.13.3 New Page?
- 13.14 Function Keys
- 13.15 Block Mode Options
- 13.15.1 Forms Display
- 13.15.2 Send Entire Block ?
- 13.15.3 Region to Send
- 13.15.4 Block/Page terminator
- 13.16 Locks
- 13.17 Screen Saver {Scrn Saver}
- 13.18 Printer
-
- 14. Computer Set-Up (Configure) Details
-
- 14.1 Getty (used in /etc/inittab)
- 14.1.1 Introduction to Getty
- 14.1.2 Getty exits after login (and can respawn)
- 14.1.3 If getty run from command line: Programs get stopped
- 14.1.4 agetty (may be named getty)
- 14.1.4.1 Agetty's auto-detection of parity problems
- 14.1.4.2 8-bit data bytes (plus parity)
- 14.1.5 getty (part of getty_ps)
- 14.1.6 mgetty
- 14.2 Stty & Setserial
- 14.3 Setserial
- 14.3.1 Important information
- 14.3.2 Introduction
- 14.3.3 Serial module unload
- 14.3.4 Giving the setserial command
- 14.3.5 Configuration file
- 14.3.6 Probing
- 14.3.7 Boot-time Configuration
- 14.3.8 Edit a script (required prior to version 2.15)
- 14.3.9 Configuration method using /etc/serial.conf, etc.
- 14.3.10 IRQs
- 14.3.11 Laptops: PCMCIA
- 14.4 Stty
- 14.4.1 Introduction
- 14.4.2 Flow control options
- 14.4.3 Using stty at a "foreign" terminal
- 14.4.3.1 Old redirection method
- 14.4.4 Two interfaces at a terminal
- 14.4.5 Where to put the stty command ?
- 14.5 Terminfo & Termcap (brief)
- 14.6 Setting TERM and TERMINFO
- 14.6.1 What is the terminfo name of my terminal ?
- 14.7 Rarely Needed /etc/ttytype File
- 14.8 Login Restrictions
- 14.9 Run Command Only If TERM=my_term_type
- 14.9.1 Example for ls Function
- 14.10 Character Mapping: mapchan
-
- 15. Terminfo and Termcap (detailed)
-
- 15.1 Intro to Terminfo
- 15.2 Terminfo Database
- 15.2.1 Introduction
- 15.2.2 Where is the database located ?
- 15.2.2.1 Compiled database locations
- 15.2.2.2 Source-code database locations
- 15.2.3 Terminfo Compiler (tic)
- 15.2.4 Look at Your Terminfo
- 15.2.5 Deleting Data Not Needed
- 15.3 Bugs in Existing Terminfo Files (and Hardware)
- 15.4 Modifying Terminfo Files
- 15.5 Init String
- 15.6 TERM Variable
- 15.7 Terminfo/Termcap Documents
-
- 16. Using the Terminal
-
- 16.1 Intro to Using the Terminal
- 16.2 Starting Up the Terminal
- 16.3 Terminal (Serial) Device Driver
- 16.4 Problems with Editors
- 16.4.1 emacs
- 16.4.2 vi and Cursor-Keys
- 16.5 Bugs in Bash
- 16.6 Color ls Corruption
- 16.7 Display Freezes (hung terminal)
- 16.8 Corrupted Terminal Interface
- 16.8.1 Symptoms and some fixes
- 16.8.2 Sent terminal binary characters
- 16.8.3 Reset command was broken but now fixed
- 16.8.4 Character corruption
- 16.8.5 Abnormally exited a program
- 16.9 Special (Control) Characters
- 16.9.1 Command-Line Editing
- 16.9.2 Interrupting (& Quit, Suspend, EOF, Flush)
- 16.9.3 Stop/Start Scrolling
- 16.9.4 Take next character literally
- 16.10 Viewing Latin1 Files on a non-Latin1 terminal
- 16.11 Eliminating Overstriking in Files
- 16.12 Inspecting the Interface
- 16.13 Changing the Terminal Settings
- 16.13.1 setterm
- 16.13.2 tput
- 16.13.3 echo
- 16.13.4 Saving changes
- 16.14 Multiple Sessions
- 16.15 Logging Out
- 16.16 Chatting between Terminals, Spying
- 16.17 Sharing the Serial Port
- 16.18 Browsers for Terminals
-
- 17. Special Uses for a Terminal
-
- 17.1 Make a Serial Terminal the Console
- 17.1.1 For Kernels 2.2 or higher
- 17.1.2 For Kernels before 2.2
- 17.2 Run Linux without a Monitor
- 17.3 Use a Keyboardless Terminal as the Monitor
- 17.3.1 How it works
- 17.3.2 Example configuration
-
- 18. Trouble-Shooting
-
- 18.1 Terminal Was Working OK
- 18.2 Terminal Newly Installed
- 18.3 Is the Terminal OK ?
- 18.4 Missing Text
- 18.5 All Keys Work Erratically; Must Hit a Key a Few Times
- 18.6 ... respawning too fast: disabled for 5 minutes
- 18.6.1 What's happening
- 18.6.2 Getty line in /etc/inittab file incorrect
- 18.6.3 No modem control signal
- 18.6.4 No such serial device
- 18.6.5 No serial support
- 18.6.6 Key shorted
- 18.7 Fails Just After Login
- 18.8 Can't Login
- 18.9 Garbled Login Prompt
- 18.10 No Login Prompt
- 18.10.1 Terminal was working OK
- 18.10.2 More diagnose
- 18.10.3 Diagnose problem from the console
- 18.10.4 Measure voltages
- 18.11 Displays Foreign/Weird Characters/Symbols
- 18.12 Displays Escape Sequences
- 18.12.1 Telnet
- 18.12.2 Terminal set to display escape sequences
- 18.13 Slow: pauses of several seconds between bursts of characters
- 18.14 Terminal doesn't scroll
- 18.15 Serial Monitoring/Diagnostics
- 18.16 Local Mode
- 18.17 Serial Electrical Test Equipment
- 18.17.1 Breakout Gadgets, etc.
- 18.17.2 Measuring voltages
- 18.17.3 Taste voltage
-
- 19. Repair & Diagnose
-
- 19.1 Repair Books & Websites
- 19.1.1 Books
- 19.1.2 Websites
- 19.2 Safety
- 19.3 Appearance of Display
- 19.4 Diagnose
- 19.4.1 Terminal Made a Noise or Smoked
- 19.4.2 Terminal Made No Noise
- 19.5 Detective work
- 19.6 Error Messages on the Screen
- 19.6.1 Keyboard Error
- 19.6.2 Checksum Error in NVR
- 19.7 Capacitors
- 19.8 Keyboards
- 19.8.1 Interchangeability
- 19.8.2 How They Work
- 19.8.3 Modern vs Old Keyboards
- 19.8.4 One Press Types 2 Different Characters
- 19.8.5 Keyboard doesn't work at all
- 19.8.6 Typing b displays bb, etc. (doubled)
- 19.8.7 Row upon row of the same character appears
- 19.8.7.1 Key sticks in down position (individual switches)
- 19.8.7.2 Key electrically shorted
- 19.8.8 Liquid spilled on the keyboard
- 19.8.9 Cleaning keyboard contacts
- 19.8.9.1 Keyboards with membranes
- 19.8.9.2 Keyboards with individual switches
-
- 20. Appendix A: General
-
- 20.1 List of Linux Terminal Commands
- 20.1.1 Sending a command to the terminal
- 20.1.2 Configuring the terminal device driver
- 20.1.3 Terminfo
- 20.1.4 Other
- 20.2 The Internet and Books
- 20.2.1 Terminal Info on the Internet
- 20.2.2 Books related to terminals
- 20.2.3 Entire books on terminals
- 20.2.4 Books with chapters on terminals
- 20.3 Non-Linux OSs
-
- 21. Appendix B: Escape Sequence Commands Terminology
-
- 21.1 Esc Sequence List
- 21.2 8-bit Control Codes
- 21.3 Printer Esc
- 21.4 Reports
- 21.5 Cursor Movements
- 21.6 Pages (definition)
-
- 22. Appendix C: Serial Communications on EIA-232 (RS-232)
-
- 22.1 Intro to Serial Communication
- 22.2 Voltages
- 22.2.1 Voltage for a bit
- 22.2.2 Voltage sequence for a byte
- 22.3 Parity Explained
- 22.4 Forming a Byte (Framing)
- 22.5 Limitations of EIA-232
- 22.5.1 Low Speed & Short Distance
- 22.5.2 Successors to EIA-232
- 22.5.3 Line Drivers
- 22.6 Synchronization & Synchronous
- 22.6.1 How "Asynchronous" is Synchronized
- 22.6.2 Defining Asynchronous vs Synchronous
- 22.6.3 Synchronous Communication
- 22.7 Block Mode
- 22.7.1 Introduction to Block Mode
- 22.7.2 Types of Block Modes, Forms
- 22.7.3 Efficiency
- 22.7.4 Problems with block mode
- 22.8 EIA-232 (RS-232) Books
- 22.9 Serial Software
-
- 23. Appendix D: Notes by Brand/Model
-
- 23.1 Adds
- 23.2 CIT
- 23.3 IBM Terminals
- 23.3.1 IBM 3153
- 23.4 Teletypes
- 23.5 VT (DEC)
- 23.6 Links
- 23.7 Qume
- 23.8 Wyse Terminals
- 23.8.1 Wyse 50
- 23.8.2 Wyse 60
- 23.8.3 Wyse 85
- 23.8.4 Wyse 99-GT
- 23.8.5 Wyse 150
-
-
- ______________________________________________________________________
-
- 1. Introduction
-
- For a quick attempt to install a terminal see ``Quick Install''.
-
-
- 1.1. Copyright, Trademarks, Disclaimer, & Credits
-
- 1.1.1. Copyright
-
- Copyright 1998-2001 by David S. Lawyer.
-
- Please freely copy and distribute (sell or give away) this document in
- any format. Send any corrections and comments to the document
- maintainer. You may create a derivative work and distribute it
- provided that you:
-
-
- 1. If it's not a translation: Email a copy of your derivative work (in
- a format LDP accepts) to the author(s) and maintainer (could be the
- same person). If you don't get a response then email the LDP
- (Linux Documentation Project): submit@en.tldp.org.
-
- 2. License the derivative work in the spirit of this license or use
- GPL. Include a copyright notice and at least a pointer to the
- license used.
-
- 3. Give due credit to previous authors and major contributors.
-
- If you're considering making a derived work other than a translation,
- it's requested that you discuss your plans with the current
- maintainer.
-
-
- 1.1.2. Disclaimer
-
- While I haven't intentionally tried to mislead you, there are likely a
- number of errors in this document. Please let me know about them.
- Since this is free documentation, it should be obvious that I cannot
- be held legally responsible for any errors.
-
-
- 1.1.3. Trademarks.
-
- Any brand names (starts with a capital letter such as MS Windows)
- should be assumed to be a trademark). Such trademarks belong to their
- respective owners.
-
-
-
- 1.1.4. Credits
-
- Much of the section "Physical Connection" is from Serial-HOWTO v.
- 1.11 (1997) by Greg Hankins (with his permission). His "How Do I Set
- Up A Terminal Connected To My PC?" was incorporated into v1.00 at
- various places. v1.09 has about 25 changes (and error corrections)
- suggested by Alessandro Rubini who reviewed this HOWTO. Jeremy Jon
- Spykerman told me about using a keyboardless terminal as a console for
- a monitorless PC (using ttysnoop). In 2001 (v1.26) I fixed about 25
- typos, etc. found by Alain Cochard:
-
-
- 1.2. Future Plans: You Can Help
-
- Please let me know of any errors in facts, opinions, logic, spelling,
- grammar, clarity, links, etc. But first, if the date is over a few
- months old, check to see that you have the latest version. Please
- send me any info that you think belongs in this document.
-
- Starting with version 1.00, a first attempt was made to help people
- set up terminals without recourse to a terminal manual. Much more is
- needed in this respect. One way to solve this problem would be for
- more terminal manufacturers put their manuals on the Internet. Wyse
- has already done so. I suggest that you encourage others to do so (if
- they haven't already). The task of providing information on how to
- configure most terminals in this HOWTO is daunting. There are so many
- different terminals, but there are far fewer models than there used to
- be in the 1980,s so the task is not totally infeasible.
- Please send me any surplus terminal manuals which you may have,
- especially on terminals made within the past 10 years (but I'll accept
- older ones also). Also, you might want to write up something on a
- certain terminal to put in the Appendix D: Notes by Brand Name.
-
-
- 1.3. New Versions of this HOWTO
-
- New versions of the Text-Terminal-HOWTO should be released every few
- months or so. They will be available to browse and/or download at LDP
- mirror sites. For a list of mirror sites see:
- . Various formats are available. If
- you only want to quickly check the date of the latest version look at
- . The version your
- are currently reading is: v1.36, August 2004 .
-
-
- 1.4. New in Recent Versions:
-
- For a full revision history going back to the first version see the
- source file (in linuxdoc format) at
- .
-
-
- · v1.36 Aug. 2004 Typo for "quit", etc. Should be ^\
-
- · v1.35 Mar. 2004: Wyse 60 emulator
-
- · v1.34 Dec. 2003: All (tildes) are now in text (formatting problem
- with Linuxdoc)
-
- · v1.33 Nov. 2003: revised setserial section; using minicom with
- directly connected terminals
-
- · v1.32: September 2003: man page console_codes, name: serial
- monitor/console, "init string" rewrite, netrik text browser, new
- url for terminfo
-
-
- 1.5. Related HOWTOs, etc.
-
- Go to the nearest mirror site (per above) to get HOWTOs.
-
- · Serial-HOWTO has info on Multiport Serial Cards used for both
- terminals and banks of modems. It has general technical info on
- the serial port including troubleshooting it.
-
- · Low-Level Terminal Interface
- part of "GNU C
- Library Reference Manual" (in libc (or glibc) docs package). It
- covers the detailed meaning of "stty" commands, etc.
-
- · NCURSES-Programming-HOWTO
-
- · MacTerminal mini-HOWTO
-
- · Modem-HOWTO
-
- · Serial-Programming-HOWTO
-
- · NC mini-HOWTO
-
- · NCD-X-Terminal mini-HOWTO
-
-
- · XDM-and-X-Terminal mini-HOWTO
-
- · Connecting-X-Terminals-to-Linux-Mini-HOWTO
-
- · NCD-HOWTO
-
- · Thinclient-HOWTO
-
- · Xterminal-HOWTO (old and unmaintained). It's at
-
-
-
- 1.6. Terminology Used in this Document
-
- Configuration means the same as set-up. While Linux commands take
- options (using - or -- symbols), options in a broader sense include
- various other types of choices. Install in the broad sense includes
- setting up (configuring) software and hardware. A statement that I
- suspect is true (but may not be) ends with 2 question marks: ?? If
- you know for sure, let me know.
-
-
- 1.7. What is a Terminal ?
-
- A real terminal consists of a screen and keyboard that one uses to
- communicate remotely with a (host) computer. One uses it just like it
- was a personal computer but the terminal is remote from its host
- computer (on the other side of the room or even on the other side of
- the world). Programs execute on the host computer but the results
- display on the terminal screen. The terminal's computational ability
- is relatively low (otherwise it would be a computer and not a
- terminal). The terminal is generally limited to the ability to
- display what is sent to it (possibly including full-screen graphics)
- and the ability to send to the host what is typed at the keyboard.
-
- A text-terminal only displays text on the screen without pictures. In
- the days of mainframes from the mid 1970's to the mid 1980's, most
- people used real text-terminals to communicate with computers. They
- typed in programs, ran programs, wrote documents, issued printing
- commands, etc. A cable connected the terminal to the computer (often
- indirectly). It was called a terminal since it was located at the
- terminal end of this cable. Some text-terminals were called "graphic"
- but the resolution was poor and the speed slow by today's standards
- due to the high cost of memory and the limited speed of the
- conventional serial port, etc.
-
- Today, real terminals are not as common as they once were and most
- people that use terminals use a personal computer to emulate a
- terminal. Almost everyone who uses Linux uses terminal emulation.
- Without X Window, one uses a text interface (virtual terminal). It's
- also called a command line interface. In X Window one can get one or
- more terminal windows (xterm, rxvt, or zterm). All these use software
- to emulate a real terminal.
-
- A real text-terminal is different from a monitor because it's a
- different electronic setup. A text terminal is often connected to a
- serial port of the computer via a long cable. Thus, in contrast to a
- monitor which is usually located right next to the computer, a
- terminal may be quite a distance away from its host computer. For a
- monitor, the video card inside a computer stores the video image. For
- a terminal, the equivalent of this video card is built right into the
- terminal but since text terminals are often monochrome without much
- graphics, the capabilities of its "video card" are rather weak. Also,
- most text terminals do not have mice.
-
-
- In network client-server terminology, one might think that the
- terminal is the client and that the host computer is the server. The
- terminal has been called a "thin client" by some. But it is not
- actually a "client" nor is the host a "server". The only "service"
- the host provides is to receive every letter typed at the keyboard and
- react to this just like a computer would. The terminal is like a
- window into the computer just like a monitor (and keyboard) are. You
- may have already used virtual terminals in Linux (by pressing Left
- Alt-F2, etc.). A real terminal is just like running such a virtual
- terminal but you run it on its own terminal screen instead of having
- to share the monitor screen. In contrast to using a virtual terminal
- at the console (monitor), this allows another person to sit at a
- terminal and use the computer simultaneously with others.
-
-
- 2. Types of Terminals
-
- 2.1. Dumb Terminals
-
- There are various conflicting definitions of "dumb terminal" but as
- time goes by, more and more terminals are called dumb. This document
- mainly covers text terminals which display only text on the screen.
- It could have been titled "Dumb-Terminal-HOWTO". But in some
- magazines articles, any terminal, no matter how smart, including ones
- which present a full graphical user interface (GUI), are called dumb.
- If all terminals are "dumb" then there is no point of prefixing the
- word "dumb" to terminal (except as a sales pitch to sell computers or
- the like in place of "smart" terminals). Due to the ambiguous meaning
- of "dumb terminal" it is not classified here as a type of terminal.
-
-
- 2.2. Text Terminals
-
- For a text terminal, a 2-way flow of information between the computer
- and the terminal takes place over the cable that connects them
- together. This flow is in bytes (such as ASCII) where each byte
- usually represents a printable character. Bytes typed at the keyboard
- go to the computer and most bytes from the computer are displayed on
- the terminal screen. Special control bytes (or sequences of bytes)
- from the computer tell the terminal where to move the cursor to, what
- to erase, where to begin and end underlining and/or blinking and/or
- bold, etc. There are often hundreds of such special commands and most
- terminals can even change fonts.
-
- The communication uses characters (letters) encoded using a code chart
- for the character set being used. Usually, the first 128 bytes out of
- 256 possible bytes use ASCII codes. Terminals for Unix-like systems,
- normally connect to computers via a cable running between the
- asynchronous serial ports (RS-232-C = EIA-232-D) of the host computer
- and the terminal. Sometimes the connection is via modem or terminal
- server, etc.
-
- Other names for text terminals are "serial monitor", "serial console"
- (if it's used like a console), "serial terminal", "dumb terminal",
- "character-cell terminal", "character terminal", "ASCII/ANSI
- terminal", "asynchronous terminal", "data terminal", "video terminal",
- "video display terminal" (VDT), and "green terminal" (since many used
- green displays). The names "serial monitor" and "serial console" may
- refer to a PC that is running a program to emulate a text terminal.
- In olden days "video display unit" (VDU) meant text terminal but
- strictly speaking, it excludes the keyboard.
-
- "Block mode" was used exclusively by old IBM mainframe terminals but
- many modern terminals also have this capability (which is not used
- much). In block mode, the characters you type are temporarily
- retained in the terminal memory (and may possibly be edited by a
- built-in editor at the terminal). Then when the send key (or the
- like) is pressed, a block of characters (sometimes just a line of
- characters) is sent to the computer all at once. Block mode (as of
- late 1998) is not supported by Linux. See section ``Block Mode''.
-
-
- 2.3. Graphic GUI Capabilities of Text Terminals
-
- Many text terminals can display bit-mapped images, but not in color.
- Unfortunately, the popular image formats used on the Internet are not
- supported. The protocols for terminal graphics include: Tektronix
- Vector Graphics, ReGIS (DEC), Sixel (DEC), and NAPLPS (North American
- Presentation Level Protocol Syntax).
-
- Even without bit-mapped images, ordinary text terminals can sort of
- display images. One may form arrows <--- and draw boxes with _ and
- |. With special graphic character sets that have a lot of special
- characters for line drawing, even more is possible. But even without
- a graphic character set, one may produce "ascii graphics" art. The
- term "graphics terminal" usually means a terminal that can display bit
- mapped images. However, this term is sometimes applied also to text-
- only terminals since text is a limited form of graphics.
-
-
- 2.3.1. Graphics GUI displays
-
- There are two basic types of graphics displays: raster and vector
- (rarely used). Raster graphics (bit-mapped) puts dots on the screen
- by horizontal scan lines drawn by an electron beam (or by activating
- pixels or dots on a flat screen). Vector graphic displays were
- intended to be used for monochrome screens that don't have any dots.
- They use smart electronics to draw lines and curves with an electron
- beam that can move in any direction (at any angle and location). True
- vector graphics draws high quality lines without zig-zags but is both
- rare and expensive. For more details see
- . Raster graphics is almost universally
- used today for both PCs and text terminals. For PCs, images encoded
- in vector graphic format are sometimes used but they are translated to
- raster graphics format for display (with a resulting drop in image
- quality).
-
-
- 2.4. Thin Clients (Terminals ?)
-
- 2.4.1. Introduction
-
- Since "thin clients" are not text terminals, this HOWTO only provides
- a brief overview of them. There are other HOWTOs that cover them in
- more detail. See ``Related HOWTOs, etc.''. Thin clients are thin
- (minimal) client computers that behave something like terminals.
- Since text terminals (except for very old ones) run an embedded
- operating system, they are also like a computer. Thin-clients need
- more computing power. In contrast to text-terminals thin clients all
- display a modern high-speed GUI. They are dependent on more powerful
- computers (servers) for their operation. For a true thin client
- terminal, the computing work and disk storage will all be done on the
- server. At the other extreme, most of this work and storage is done
- at the thin client but some things such as administration, still
- depend on the server. Since such a client is not really "thin" it may
- more correctly be called a "fat client".
-
- Such clients may be created from an ordinary PC by using software or
- may be a stand-alone piece of hardware. But the stand-alone hardware
- will often use a conventional PC monitor plus a small box for the
- computer part of the hardware. Linux seems to favor the use of PCs as
- a client.
- Some claim that text-terminals are also thin clients but they are not
- really since they don't conform to the client-server model. However,
- connecting a terminal via telnet does invoke the client-server model
- in the use of telnet as a means of transport of data. But the
- relation of the text-terminal to it's host is not one of client-
- server. The text-terminal is just another means of access to the
- computer just like the monitor and its keyboard is. One could apply
- this same reasoning to a thin client and say that the client-server
- relationship is only for the transport of data.
-
- Thus a thin client is like a terminal. It has a GUI with a mouse that
- makes it seem like you are using a computer. You are, but that
- computer may be far away and have many other people using it at the
- same time you are. Communication is over a high speed network cable
- or even over the Internet. Some thin clients can, in addition,
- emulate a text terminal and have a serial port connector for that
- purpose. One even has a USB interface.
-
- There are various types of thin clients. One type is the "Window
- Terminal" which runs under MS servers (and software). Another type is
- the "network computer" which is supposed to be platform neutral. This
- implies they should work with both MS Windows and Linux but early
- models may not be easy to use with Linux. For Linux, the X Window
- protocol is used. See ``Thin clients and NCs under Linux''
-
-
- 2.4.2. MS Window terminals
-
- These are true terminals since all the computing work is done by a
- server running Windows. They are also called "Window-based Terminals"
- (WBT). These terminals (clients) are something like computers since
- they often run an embedded operating system such as Linux or
- Microsoft's CE, NT, or XP. It's often stored in flash memory so that
- it may be updated. Also, ordinary PCs can be used as clients
- (including, in some cases, Linux PCs) with the appropriate software,
- Some clients can support X Window (from a Linux server) and some can
- emulate text-terminals. Many so called "network computers" can also
- run X Window. This will be discussed in the next section.
-
- The server for these clients usually runs MS's Terminal Services (for
- Windows 2000 servers). Prior to this there was Windows NT Terminal
- Server Edition (starting mid 1998 with codename "Hydra"). MS uses RDP
- (Remote Desktop Protocol) which is based on the ITU T.120 protocol.
- In addition, there is an optional ICA protocol (with added features)
- which can inter-operate with RDP.
-
- Prior to this there was a modified Windows NT 3.51 (1995) called
- "WinFrame" by Citrix using the proprietary ICA protocol (Independent
- Computing Architecture). After MS came out with its own terminal
- server, Citrix still remained on the scene. It created MetaFrame
- software (formerly pICAsso) as an add-on to MS's Terminal Server (or
- Services) so that it could support ICA-based terminals and provide
- other additional features. Before MS got into the act, there were
- other proprietary systems for terminals that could display the MS
- Windows GUI but later on they all switched to support Microsoft's
- system.
-
- PCs running Linux can be turned into ICA based client terminals using
- "free" (in price only) proprietary ICA client software from Citrix:
- Citrix Systems, Inc. . Unfortunately, MS requires that you purchase a
- license to cover the clients, even if the clients all run Linux. So
- if you want to save money on software costs by using Linux, you'll
- have to go all-Linux and use both Linux servers and clients using the
- free X-Window protocol.
-
- The above is sometimes called "network computing" since the terminals
- and servers connect to each other over a network (such as the common
- TCP/IP based network used by both Linux and MS). Network computers
- may be somewhat different as described below.
-
-
- 2.4.3. Network computers (NCs)
-
- These are neither true computers nor true terminals but are something
- in-between. One type of network computer (NC's) is a computer with a
- CPU but no hard Disk. The OS it needs to run is sent to it over a
- network. NCs are full-graphics and use the services of a server
- computer. They are a little different from terminals since some (or
- most) of the programs they run may execute on their own CPU chip.
- Running a browser was supposed to be one of their primary functions
- and thus Java code applets may be sent to them for execution. Many
- NCs support X Window so that one may use a Linux server to support it.
- Such a server may be called a "Linux Terminal Server". IBM called
- their NC a "NetStation" but now calls it "NetVista". They should work
- on Intranet type networks and NetVista can run the the Linux OS.
-
- Wintel came out with a "NetPC" which, unlike the above, is almost a PC
- computer. However, it has no removable disks so users can't install
- their own software or obtain copies of anything.
-
-
- 2.4.4. Thin clients and NCs under Linux
-
- There is a "Linux Terminal Server Project" (LTSP or ltsp) to use Linux
- as a server for diskless thin clients. They use X Window and by
- default, applications run on the server. But with additional effort,
- one can set it up so that some or all applications run on the
- "terminal". See .
-
- "Terminal" in LTSP is actually a thin (or fat) client. This project's
- client can also run a telnet session and thus behave like a text-
- terminal. A software package named "lts" for the LTSP is available in
- the major Linux distributions.
-
- It's claimed that if one has only a few "terminals", they will work
- without the ltsp software. But if one has many "terminals", ltsp
- software is needed. So use ltsp if what you want to do is to use old
- PCs, etc. as diskless thin clients. It works OK on systems with over
- 100 thin-client workstations.
-
- Linux provides NFS (Network File System) so that if ordinary computers
- are connected to each other via a network, then a person on one
- computer can run programs on another computer. Such a program sends
- messages over the network so that it appears just like a program was
- being run by your local computer. But such a program is actually
- being run on another computer on the network. It works also with X
- Window so that one may see GUI images generated on another computer.
-
- Linux also allows a computer to be diskless and boot over a network.
- See the "Terminal Server Project" above which has special software for
- this purpose. Network-boot-HOWTO gives an overview. Older documents
- are Diskless-HOWTO and Diskless-root-NFS-HOWTO. Thus using a diskless
- computer which runs NFS enables you to run programs on another
- computer (the server). This is just like using a NC (Network
- Computer). It's not really a NC but it's emulating a type of NC.
- It's also often called a "terminal" and in some sense it is.
-
- Thus if you have an old PC with an ethernet card (NIC) you may be able
- to use it as a NC. One source of info on this is Thinclient-HOWTO.
- Even if your old PC doesn't have a NIC, you could still use it to
- emulate a text-terminal. See ``Terminal Emulation''.
- There are also a number of genuine Network Computers (NC) that will
- work with a Linux server. Today some NCs run the Linux OS inside the
- NC. Before Linux became popular, NCs didn't run the Linux OS but
- required some other OS. But even if the NC uses a non-linux OS, it's
- often possible to make it work with a Linux Server. The non-linux OS
- is simply stored as files on the Linux Server. Then when the NC
- starts up it sends a message to the Linux Server asking for the non-
- linux OS files. This non-linux OS is thus sent to the NC over the
- network and the NC boots.
-
- The Linux Server runs the NFS and X Window both of which must be
- supported by the NC. This enables one to use the NC as if it were an
- X Window terminal.
-
- There are some Linux HOWTOs for certain brands of NCs:
-
-
- · JavaStation-HOWTO (by Sun)
-
- · NC-HOWTO (IBM NetStation)
-
- · NCD mini-HOWTO (NCD-ThinSTAR)
-
- · NCD-X-Terminal mini-HOWTO
-
- · XDM-and-X-Terminal mini-HOWTO
-
-
- 2.4.5. Hardware hookups
-
- There are 3 different types of hardware arrangements for thin clients.
- The first type just uses a PC computer as a thin client by emulating a
- thin client. It really isn't a thin client but it behaves like one.
- The second type looks just like a text-terminal. It just looks like a
- monitor, with a connector for a keyboard and another connector for a
- network cable. It's a dedicated thin client and can't be used for
- anything else. The third type looks like a tiny computer. It uses a
- standard PC monitor and keyboard both of which plug into a small box
- which is a "thin" computer. This box provides an interface between
- the monitor/keyboard and the network.
-
-
- 2.4.6. History and the future
-
- Promoters of NCs and related Window-Terminals projected that they
- would soon replace millions of PCs. In 1998 about .7 million thin
- clients were sold worldwide with (about 27% of them being NCs). In
- 1999 it dropped to .6 million but went up to .9 million in 2000 (vs.
- 1.3 million predicted). In 2001 it reached 1.09 million with 1.4
- million predicted for 2002.
-
- Microsoft servers (as of 2003) still dominate the market, but the
- clients may run Linux for which users still have to pay license fee
- for each Linux client to Microsoft. Thus free all-linux systems are
- gaining ground.
-
- A major reason why growth was not as rapid as predicted is that PCs
- have come down in price in recent years so that they are often not
- much more expensive than a thin client. However, it's argued that
- even though thin clients may cost the same as PCs, the maintenance and
- administration costs are less. Note that thin clients sometimes
- replace text terminals instead of PCs.
-
-
-
- 2.5. Emulation on a PC
-
- Since a PC has a screen and keyboard (as does a terminal) but also has
- much more computing power, it's easy to use some of this computing
- power to make the PC computer behave like a text terminal. This is
- called "terminal emulation". They usually emulate text-terminals.
- See ``Terminal Emulation''
-
-
- 3. Quick Install
-
- This is a quick procedure to install a terminal without going through
- a ``Setup'' procedure for both the terminal and the host computer. It
- probably will not work right if the terminal happens to have been set
- up incompatible with the computer. If you don't understand some of it
- you'll need to consult other parts of this document for more info.
-
- To install a terminal, first look in /etc/termcap or terminfo.src to
- find an entry for it (see ``Terminfo and Termcap (detailed)'').
- Figure out what serial port you'll connect it to and what the tty
- designation is for that port (e.g. ttyS1 or tts/1), see ``Device
- Names''). As the root user, edit /etc/inittab and add a getty command
- next to the other getty commands. The format of the getty command
- depends on which getty program you use. agetty (called just getty in
- the Debian distribution) is the easiest (no configuration file). See
- the "info" or "man re getty. For getty parameters use the terminfo
- (or termcap) name (such as vt100) for your terminal. Type in a baud-
- rate that the terminal supports. But if you set the baud too high you
- may need to use (See``Flow Control'').
-
- Then physically connect the main serial port of the terminal to the
- chosen serial port of the computer with a null-modem cable and turn on
- the terminal. Don't expect most ready-made cables to be wired
- correctly for hardware flow control. Make sure the baud-rate of the
- terminal is set the same as you gave to getty and that its "data bits"
- is 8. Then at the computer console type "init q" to apply the changes
- you made to the inittab file. You should now see a login prompt at
- the terminal. If you don't, tap the terminal's return key. If this
- doesn't work read more of this document and/or see ``Trouble-
- Shooting''.
-
-
- 4. Why Use a Terminal ?
-
- 4.1. Intro to Why Use a Terminal
-
- PC's are so powerful today that just one PC can often support several
- persons using it at once, especially if they are doing low-load tasks
- such as text editing, data entry, etc. One way to do this is to
- connect a number of terminals to a single PC (or other host computer)
- by modems or direct cable connection. To do this, it's usually best
- to have a multi-user operating system such as Linux so that each user
- at a terminal can use the computer independently. This has been
- called "time sharing" but it's not good terminology today since
- "distributed" computing over a network is also a type of time sharing.
- It might be better described as "centralized" computing. But the
- central computer may be connected to the rest of the world via a
- network so that terminal users may send email, browse the Internet
- with the lynx browser, etc. So it's not exactly "centralized" either.
-
- Terminals have seldom been used with PC's because the popular
- operating systems used for them (Windows, DOS, and Mac) were not
- multiuser until 1998 (available for MS Windows NT) and previously
- could not support terminals very well. Now that Linux, a multiuser
- operating system, is freely available for PC's, the use of terminals
- with PC's becomes more feasible. The drawback is that text terminals
- are not smart enough to support the type of graphical user interface
- (GUI) that many computer users today normally expect.
-
-
- 4.2. Lower Hardware Costs ?
-
- When Computers (including PCs) were quite expensive, lower hardware
- costs was a significant advantage of using terminals. Today with
- cheap PCs, the cost savings is problematical. Here's what I wrote
- years ago when PCs were more expensive. It's still true today but of
- less significance.
-
- If several people use the same computer as the same time, there is a
- reduction in the amount of hardware needed for the same level of
- service. One type of savings is due to code sharing. The application
- files on hard disks are shared as well as shared libraries in memory
- (even when people are running different programs provided they use
- some of the same functions in their code). Another type of savings is
- due to reduction of peak load. The hardware of a single PC may be
- idle most of the time as people slowly type in information, think,
- talk, or are away from their desks. Having several people on the same
- computer at once makes good use of much of this idle time which would
- otherwise be wasted.
-
- These savings are substantial. One may roughly estimate (using
- statistical theory) that for 9 persons (8 terminals & 1 console) the
- shared PC only needs only about 3 times as much capacity (in memory,
- disk storage, CPU power, etc.) as a single PC in order to provide the
- same level of service per person. Thus the computational hardware for
- such a shared system should only cost about 1/3 as much per user.
- However, the cost of the display hardware (CRT's, keyboards, video
- electronics, etc.) is about the same for both cases. The terminals
- have the added cost of requiring additional serial ports at the host
- computer.
-
- For a fair comparison with PC's, the terminals should have the same
- capabilities as the PC monitors. Unfortunately, color graphic
- terminals for Linux (X Window) with high speed communication cost
- about as much as a PC so in this case there not much (if any) savings
- in hardware costs. But for text terminals there will be some savings,
- especially if the terminals are obtained used at low cost.
-
-
- 4.3. Control of Software
-
- For centralized computing, software (and the updates to software) only
- need be installed and configured on one host computer instead of
- several. The person in charge of this computer may control and
- configure the software which is installed on it. This is advantageous
- if the person controlling the host computer does an excellent job and
- knows about the needs and preferences of the other users. Users can
- be restricted in playing games or surfing the Internet by not
- installing the software (or by otherwise restricting access to it).
- Whether or not centralized control is desirable depends on the
- situation.
-
-
- 4.4. Hardware Upgrades
-
- With terminals, the computer hardware upgrades take place on only one
- computer instead of many. This saves installation labor effort.
- While the cost of the hardware for the host computer upgrade will be
- more than that for a single PC (since the host needs more computing
- power than a PC), the cost will be significantly less than upgrading
- the hardware of a number of PC's being used instead of terminals.
-
- 4.5. Other Advantages of Terminals
-
-
-
- · The elimination of noise from fans and disk drives (unless your
- using a PC to emulate a terminal).
-
- · The users of the terminals can share data and files and send e-mail
- to each other. It's similar to a local network.
-
-
- 4.6. Major Disadvantages of Terminals
-
-
-
- · Text terminals have no high-speed graphic display (or high
- resolution graphics) although they can often use graphic character
- sets to draw boxes, etc. This lack limits the software that may be
- used on it.
-
- · If the host computer goes down, then no one can use the terminals
- either (unless there is a "standby" host computer to connect to).
-
-
- 4.7. Are Text Terminals Obsolete ?
-
- Text terminals are technologically obsolete because for a slightly
- higher cost of hardware, one could build a smarter terminal (with the
- same quality of display). This wasn't always the case since around
- 1980 memory cost thousands of dollars per megabyte. Today with low
- costs for memory and processors, one could turn a text terminal into a
- GUI graphic terminal for only about a 10% or 20% increase in hardware
- cost. Since a PC can emulate a terminal, almost everyone using
- computers has a terminal emulator available.
-
- The reasons that text terminals are not fully obsolete are:
-
- · The resolution of characters on the screen is better on monochrome
- terminals than for monitors in text mode.
-
- · Many people don't need full screen graphics.
-
- · Since running a text-terminal (in contrast to a GUI-graphics
- terminal) doesn't consume much of a modern PC's resources, a large
- number of terminals may be efficiently run from one PC.
-
-
- 5. Overview of How Terminals Work (in Linux)
-
- See also section ``Some Details on How Terminals Work''
-
-
- 5.1. Device Names
-
- Each terminal is connected to a serial port on the host computer
- (often just a PC). The ports have names/numbers. The first few are:
- tts/0 (or ttyS0), tts/1 (or ttyS1), tts/2 (or ttyS2) etc.
-
- These are represented by special files found in the /dev (device)
- directory. tts/0 (or ttyS0) corresponds to COM1 in DOS or Windows.
- tts/1 (or ttyS1) is COM2, etc. See ``Terminal Special Files'' for
- details on these and related "devices".
-
-
-
- 5.2. Login/Logout
-
- When the host computer starts up it runs the program getty. The getty
- program runs the "login" program to log people in. See ``Getty (used
- in /etc/inittab)''. A "login:" prompt appears on the screen. People
- at the terminals log in (after giving their passwords) and then have
- access to the computer. When it's time to shut the terminal down, one
- normally logs out and turns the terminal off. See ``Login
- Restrictions'' regarding restricting logins (including allowing the
- root user to log in at terminal).
-
-
- 5.3. Half/Full Duplex
-
- If one watches someone typing at a terminal, the letters one types
- simultaneously appear on the screen. A naive person might think that
- what one types is being sent directly from the keyboard to the screen
- with a copy going to the computer (half-duplex like, see next
- paragraph). What is usually going on is that what is typed at the
- keyboard is directly sent only to the host computer which in turn
- echoes back to the terminal each character it receives (called full-
- duplex). In some cases (such as passwords or terse editor commands)
- the typed letters are not echoed back.
-
- Full-duplex means that there are two (dual) one-way communication
- links. Full-duplex is the norm for terminals. Half-duplex is half of
- a duplex, meaning that there is only a single one-way communication
- link. This link must be shared by communications going in both
- directions and only one direction may be used at a time. In this case
- the computer would not be able to echo the characters you type (and
- send to it) so the terminal would need to also send each character you
- type directly to the terminal screen. Some terminals have a half-
- duplex mode of operation which is seldom used.
-
-
- 5.4. Terminal Memory
-
- The image on a CRT tube will fade away almost instantly unless it is
- frequently redrawn on the screen by a beam of electrons shot onto the
- face of the tube. Since text sent to a terminal needs to stay on the
- screen, the image on the screen must be stored in the memory chips of
- the terminal and the electron beam must repeatedly scan the screen
- (say 60 times per second) to maintain the image. See ``Terminal
- Memory Details'' for more details.
-
-
- 5.5. Commands for the Terminal
-
- The terminal is under the control of the computer. The computer not
- only sends the terminal text to display on the screen but also sends
- the terminal commands which are acted on. These are ``Control Codes''
- (bytes) and ``escape sequences''. For example, the CR (carriage
- return) control code moves the cursor the the left hand edge of the
- screen. A certain escape sequence (several bytes where the first byte
- is the "escape" control code) can move the cursor to the location on
- the screen specified by parameters placed inside the escape sequence.
-
- The ``first terminals'' had only a few such commands but modern
- terminals have hundreds of them. The appearance of the display may be
- changed for certain regions: such as bright, dim, underline, blink,
- and reverse video. A speaker in a terminal can "click" when any key
- is pressed or beep if a mistake has occurred. Function keys may be
- programmed for special meanings. Various fonts may exist. The
- display may be scrolled up or down. Specified parts of the screen may
- be erased. Various types of flow control may be used to stop the flow
- of data when bytes are being sent to the terminal faster than the
- terminal can handle them. There are many more as you will see from
- looking over an advanced terminal manual or from the Internet links
- ``Esc Sequence List''
-
-
- 5.6. Lack of Standardization Solved by Terminfo
-
- While terminals made for the US all used the same ASCII code for the
- alphabet (except for IBM terminals which used EBCDIC), they
- unfortunately did not all use the same escape sequences. This
- happened even after various ANSI (and ISO) standards were established
- since these standards were never quite advanced enough. Furthermore,
- older terminals often lacked the capabilities of newer terminals.
- This might cause problems. For example, the computer might send a
- terminal an escape sequence telling it to split the screen up into two
- windows of specified size, not realizing that the terminal was
- incapable of doing this.
-
- To overcome these problems a database called "termcap" (meaning
- "terminal capabilities") was established. Termcap was later
- superceded by "terminfo". This database resides in certain files on
- the computer and has a section of it (sometimes a separate file) for
- each model of terminal. For each model (such as VT100) a list of
- capabilities is provided including a list of certain escape sequences
- available. For example blink=\E5m means that to make the cursor start
- blinking the terminal must be sent: Escape 5 m. See Section ``Termcap
- and Terminfo (detailed)'' for more details. Application programs may
- utilize this database by calling certain C-Library functions. One
- large set of such programs (over 200) is named "ncurses" and are
- listed in the manual page for "ncurses" which comes with a developer's
- ncurses package. There is also a NCURSES-programming-HOWTO.
-
-
- 5.7. The Interface
-
- The environment variable TERM is the type of terminal Linux thinks you
- are using. Most application programs use this to look up the
- capabilities in the terminfo database so TERM needs to be set
- correctly. But there is more to a correct interface than the
- computer knowing about the capabilities of the terminal.
-
- For bytes to flow from the computer to the terminal the terminal must
- be set to receive the bytes at the same baud rate (bits per second) as
- they are sent out from the terminal. If the terminal is set to
- receive at 19,200 baud and the computer sends out characters at 9600
- baud, only garbage (or perhaps nothing) will be seen on the screen.
- One selects the baud rate for a terminal (as well as many other
- features) from the terminals "set-up" menus at the terminal. Most
- terminals have a large number of options in their "set-up" menus (see
- ``Terminal Set-Up (Configure) Details''). The computer serial port
- has options also and these options must be set up in a compatible way
- (see ``Computer Set-Up (Configure) Details''.
-
-
- 5.8. Emulation
-
- Most terminals today have more than one emulation (personality or
- "terminal mode"). The terminal model numbers of terminals formerly
- made by DEC (Digital Equipment Corporation now Compaq) start with VT
- (e.g. VT100). Many other terminals which are not VT100 may be set up
- to emulate a VT100. Wyse is a major terminal manufacturer and most of
- their terminals can emulate various DEC terminals such at VT100 and
- VT220. Thus if you want to, say, use a VT320 terminal you may either
- use a real VT320 in "native" personality or possibly use some other
- terminal capable of emulating a VT320.
-
- The "native" personalities usually have more capabilities so, other
- things being equal, "native" is usually the best to use. But other
- things may not be equal. Since the Linux console emulates a VT102 it
- you may want to have a terminal emulate this (or something close to it
- such as VT100). This will help insure that some programs that may not
- handle terminals properly will still work OK on your terminal. Some
- programs will assume that you are using a VT012 if the program can't
- find a terminfo for your terminal (or can't find a certain
- capability). Thus the failure of a program to work correctly with
- your non-vt102 terminal may well be your fault if you don't provide a
- good terminfo file for your terminal. Using "native" and then
- reporting any bugs will help discover and fix bugs which might not
- otherwise get detected.
-
- The most common type of emulation is to use a PC like it was a vt100
- terminal (or the like). Programs loaded into the PC's memory do the
- emulation. In Linux (unless you're in X Window) the PC monitor
- (called the console) emulates a terminal of type "Linux" (close to
- vt100). Even certain windows within X Window emulate terminals. See
- ``Terminal Emulation''.
-
-
- 5.9. The Console
-
- On a PC, the monitor is normally the console. It emulates a terminal
- of type "Linux". One logs on to it as a virtual terminal. See ``The
- Console''. It receives messages from the kernel regarding booting and
- shutdown progress. One may have the messages that normally go to the
- console, go to the terminal. To get this you must manually patch the
- kernel, except that for kernel 2.2 (or higher) it is a "make config"
- option. See ``Make a Serial Terminal the Console''.
-
-
- 6. Terminal Special Files such as /dev/tty
-
- "tty" is an abbreviation for "Teletype". The first terminals were
- Teletypes (like remotely controlled typewriters). See subsection
- ``Teletypes''. A list of Linux devices (the stuff in the /dev
- directory) may be found in "Linux Allocated Devices" which should be
- included with kernel sources. It "describes" what each device used
- for in only a word or two but doesn't tell you how to use them.
-
-
- 6.1. Serial Port Terminals
-
- The computer considers each serial port to be a "device". It's
- sometimes called a terminal device since at one time terminals were
- the most common use for a serial port. For each such serial port
- there is a special file in the /dev (device) directory. /dev/tts/0
- (or /dev/ttyS0) is the special file for the serial port known as COM1
- in the DOS/Windows world. The device filesystem notation: tts/0 is
- replacing the older ttyS0 notation. But the older notation will be
- often used in this howto since it is still widely used and often still
- works (using symbolic links) on the newer device filesystems.
-
- To send text to a terminal you may redirect standard output of some
- command-line command to the appropriate special file. For example
- typing "echo test > /dev/ttyS1" at the command prompt should send the
- word "test" to the terminal on ttyS1 (COM2) provided you have write
- permission on /dev/ttyS1. Similarly, typing "cat my_file >
- /dev/ttyS0" will send the contents of the file my_file to COM1
- (ttyS0).
-
-
-
- 6.2. Pseudo Terminals
-
- Pseudo terminals are pairs of devices such as /dev/pty/m3 and
- /dev/pty/s3 (or respectively /dev/ptyp3 and /dev/ttyp3 if you're not
- using the device filesystem). There is no physical device directly
- associated with either of them, not even a serial port connector.
- But if a program treats s3 (ttyp3) like it was a serial port, what is
- read and written to that port appears on the other member of the pair
- m3 (ptyp3) which another program uses to read and write to. Thus two
- programs talk to each other via this method and one program (on
- s3=ttyp3) thinks it's talking to a serial port. It's something like a
- "pipe" between m3 and s3.
-
- For talking to s3 (ttyp3), any program designed to talk to a serial
- port will do. But for the other program that talks to m3 (ptyp3) it
- must have been specially written to talk to m3. It's mainly
- programmers that must concern themselves with pseudo terminals and
- most users don't need to worry about them.
-
- Here's an example: If someone connects via telnet to your computer
- over a network, the part of the telnet program handling this
- connection on your computer may wind up connected to the device m2
- (ptyp2) (a pseudo terminal port). A getty program should be running
- on the corresponding s2 (ttyp2). When telnet gets a character from
- the remote, it goes thru m2 to s2 to getty which then sends back
- "login:" routed to s2, m2, your telnet program, and then out to the
- network. Here the login program and the telnet program talk to each
- other via a "pseudo terminal". In X Window, the terminal emulator
- program, xterm (or rxvt), uses pseudo terminals. Ham radio programs
- under Linux also use them. By using certain application software, it
- is possible to have 2 or more pseudo terminals attached to the same
- physical serial port.
-
- For a pseudo terminal pair such as m3 (ptyp3) and s3 (ttyp3), the m...
- (pty...) is the master or controlling terminal and the s... (tty...)
- is the slave. The device filesystem notation makes this clear (m is
- for master, s is for slave). The slave is like a serial port so also
- think of s as standing for "serial". In the old notation, tty.. is
- like a serial port ttyS (which in olden days was just tty).
-
- Prior to the device filesystem a complex notation was used in order to
- get a large number of pseudo terminals. There are only 16 ttyp's:
- ttyp0-ttypf (f is a hexadecimal digit). To get more pairs, more
- letters such as q, r, s were used instead of p. For example the pair
- ttys8, ptys8 was a pseudo terminal pair. Later on, even more letters
- were added so as to allow even more pseudo terminals. With the device
- filesystem, we may just use, for example, /dev/pty/m57 instead of
- /dev/ttys9 for the 58th pty master. People have made the mistake of
- typing say ttys2 (which is a pseudo serial port) when they meant to
- type ttyS2 (a real serial port).
-
- The master and slave are really the same "port" but the slave is used
- by the application program and the master is used by a network program
- (or the like) which supplies (and gets) data to/from the slave port.
- The program using the slave port can run "as is" since it thinks it is
- talking to a serial port.
-
- Unix98 (available on Linux) doesn't use the above but instead uses a
- "pty master" which might be, for example, /dev/ptm3. It's slave is
- automatically created as /dev/pts/3. It thus supplies a pty on
- demand. The /dev/pts directory is considered to be a file system of
- type devpts and appears in the lists of mounted filesystems. While
- the "file" /dev/pts/3 looks like it would be an entry in the device
- filesystem, it's really a wholly different kind of filesystem.
-
-
- While other unix-like systems have a manual page for pseudo terminals
- (may be named "pty") Linux lacks one for the general user. But there
- is a man-page for programmers: (openpty or forkpty) which assumes that
- you already understand pseudo terminals. There is both a Linux pty
- module and a /usr/include/pty.h file.
-
-
- 6.3. The Controlling Terminal /dev/tty
-
- /dev/tty stands for the controlling terminal (if any) for the current
- process. To find out which tty's are attached to which processes use
- the "ps -a" command at the shell prompt (command line). Look at the
- "tty" column. For the shell process you're in, /dev/tty is the
- terminal you are now using. Type "tty" at the shell prompt to see
- what it is (see manual pg. tty(1)). /dev/tty is something like a link
- to the actually terminal device name with some additional features for
- C-programmers: see the manual page tty(4).
-
-
- 6.4. /dev/ttyIN "Terminals"
-
- N stands for an integer. One use of these in Linux is with the ISDN
- driver package: isdn4linux. The ttyIN is something like ttySN but it
- emulates a modem and can be given modem commands.
-
-
- 6.5. The Console: ttyN or vc/N
-
- In Linux the PC monitor is usually called the console and has several
- device special files associated with it: vc/0 (tty0), vc/1 (tty1),
- vc/2 (tty2), etc. When you log in you are on vc/1. To go to vc/2 (on
- the same screen) press down the 2 keys Alt(left)-F3. For vc/3 use
- Left Alt-F3, etc. These (vc/1, vc/2, vc/3, etc.) are called "virtual
- terminals". vc/0 (tty0) is just an alias for the current virtual
- terminal and it's where messages from the system are sent. Thus
- messages from the system will be seen on the console (monitor)
- regardless of which virtual terminal it is displaying.
-
- You may log in to different virtual terminals and thus have a few
- different sessions with the computer going on at the same time. Only
- the system or the root user may write to /dev/vc/0 to which
- /dev/console is sometimes linked. For more info on the console see
- ``The Linux Console''.
-
-
- 6.6. Creating a Device with "mknod"
-
- The /dev directory comes supplied with many device special files. If
- you need something that's not there you may try to create it with the
- "mknod" command. See the manual page ttys(4) for how to do this for
- serial ports. To use mknod you must know the major and minor device
- numbers. You might be able to infer the numbers you need by using the
- "ls -l" command in the /dev directory. It will display the major and
- minor numbers of existing special files.
-
-
- 7. Some Details on How Terminals Work
-
- If you know almost nothing about terminals, it's suggested that you
- first read ``Introduction'' and also read ``Overview of How Terminals
- Work''.
-
-
-
- 7.1. Terminal Memory Details
-
- The terminal screen refreshes itself at perhaps 60 times per second
- from an image stored in the memory of the terminal. For a PC the
- monitor's image is stored on the video card inside the computer but
- for a terminal, the equivalent of the video card is inside the
- terminal. For a text terminal the storage of the image uses little
- memory. Instead of putting every dot (pixel) on the screen into
- memory and requiring the storage of about a quarter-million dots, a
- much more efficient method of storage is used.
-
- A screen-full of text may be represented inside the terminal memory by
- ASCII bytes, one for each character on the screen. An entire screen
- only takes about 2K ASCII bytes. To display these characters, the
- terminal must also know the bit-map (the shape) of each of the almost
- 100 printable ASCII characters. With a bit-map of a character using
- say 15 bytes, only about 1.5K of memory is needed for the bit-maps of
- all the ASCII characters (the font). This ASCII text and font memory
- is scanned so that the resulting image is put on the screen about 60
- times each second. This is a form of shared memory where a single
- bit-map of a letter such as the letter e, is shared by all of the many
- letter e's which appear on a screen-full of text. Low memory
- requirements meant low costs to produce monitors in the early 1980's
- when the cost of memory was several thousand times higher than it is
- today (costing then several dollars per kilobyte).
-
-
- 7.2. Early Terminals
-
- The first terminals were something like remotely controlled
- typewriters which could only "display" (print on paper) the character
- stream sent to them from the computer. The earliest models were
- called ``Teletypes''. The name "tty" is just an abbreviation for
- "Teletype". Early terminals could do a line feed and a carriage
- return just like a typewriter and ring a bell when a bell character
- was received. Due to the lack of significant capabilities this was
- the first type of terminal to be labeled "dumb". This type of
- terminal interface (using a terminal type called "dumb") is sometimes
- used today when the computer can't figure out what kind of a terminal
- it is communicating with.
-
-
- 7.3. Escape Sequences and Control Codes (intro)
-
- Terminals have many capabilities some of which are always present and
- some of which require commands from the computer to change or
- activate. To exercise all these capabilities under the control of the
- computer requires that special codes be established so that the
- computer can tell the terminal what to do. There are two major type
- of such codes: escape sequences and control codes (control
- characters). There are many times more escape sequences than control
- codes.
-
-
- 7.3.1. Control codes
-
- The control codes (or control characters) consist of the first 32
- bytes of the ASCII alphabet. They include the following: carriage-
- return (cursor to far left), line-feed (cursor down one line),
- backspace, escape-character, tab, and bell. They do not normally show
- on the screen. There is usually a command which you may give to your
- terminal which will result in them being displayed when they are
- received by the terminal. It's called something like "Display
- Controls" or "Monitor". If you do this then the display may look a
- mess since escape sequences, which all start with the ESC (escape)
- control character, are no longer executed. Words which should appear
- at the top or bottom of the screen will show up in other locations.
- The escape sequences to reposition the cursor display on the screen
- but the cursor doesn't move to where the escape sequence says.
-
-
- 7.3.2. Escape sequences
-
- Since there are not nearly enough control codes to do everything (and
- for some reason, not all of them are utilized) many escape sequences
- are used. They consist of the "escape" (ESC) control character
- followed by a sequence of ordinary characters. Upon receiving an
- escape character, the terminal examines the characters following it so
- that it may interpret the sequence and carry out the intended command
- from the computer. Once it recognizes the end of a valid sequence,
- further characters received just display on the screen (unless they
- are control codes or more escape sequences). Some escape sequences
- may take parameters (or arguments) such as the coordinates on the
- screen to move the cursor to. The parameters become a part of the
- escape sequence. An ``Esc Sequence List'' is on the web for some
- terminals, but it's terse.
-
- A list of the escape sequences for your terminal should be in the
- "programmers manual" for the terminal. Except for very old terminals,
- there may be two or three hundred such sequences. If you don't have a
- such manual it's not easy to find them. Some of the sequences are
- available on the Internet. One link is ``Esc Sequence List''. By
- searching the Internet for one sequence (such as ESC[5m) you may come
- across a long list of them.
-
- Another way to determine some of them is to find the terminfo entry
- (termcap) for the terminal and mentally decode it. See ``Terminfo and
- Termcap (detailed)'' in this document and/or the ``Termcap Manual'' on
- the Internet. Unfortunately, the terminfo (termcap) for a terminal
- often does not list all of the escape sequences which the terminal has
- available for use, but fortunately, the most important ones are
- usually there.
-
-
- 7.4. Display Attributes & Magic Cookies
-
- Terminals have various methods of generating character attributes such
- as bold, reverse-video, underlining, etc. There should be no need for
- the user to worry about how this is done, except that it creates
- problems for some old terminals and there is sometimes an option for
- this in the set-up menu of newer terminals.
-
- The magic cookie method is obsolete. It's the simplest (and worst)
- method of defining attributes: Use a certain byte for the start of an
- attribute and another to end that attribute. For example, a "start
- underlining" magic cookie byte is placed just before the first word to
- be underlined. These extra bytes are put into the memory of the
- screen page, just like character bytes that display as characters.
- But this might foul up the count of the number of characters per line
- since non-printable magic cookie characters are intermingled with
- other printable characters. This sometimes causes problems.
-
- A better method which uses more memory is to assign an attribute byte
- (or half=byte, etc.) to each displayed character. This method is used
- by PC video cards (for text) for the common PC monitor.
-
-
- 8. Special Features of Some Terminals
-
-
-
- 8.1. Color
-
- While the common monochrome terminal is not a color terminal it may
- have a fixed "color" display other than white such as green or amber.
- All terminals have black (electron beam turned off = zero brightness).
- A real color terminal can change the color of the text and background
- to many different colors while a monochrome terminal can only change
- the brightness of a fixed color.
-
- However, changing the brightness, etc. gives a lot of possibilities.
- For example, a black and white (monochrome) terminal can have white,
- grey, and black by varying the brightness. Some words can be black on
- a light grey background while other are highlighted by black on white.
- In addition there is white on black, underlining, and blinking.
-
- Color works like the color on a computer monitor or TV screen. The
- CRT has three colors of dots on it with each color controlled by its
- own electron beam (3 beams). Monochrome has inherently better
- resolution since it doesn't depend on dots permanently fixed on the
- screen. For text terminals the only use of color is to differentiate
- text and this advantage is not always worth the cost of worse
- resolution. Thus monochrome may be better since it also costs less.
-
-
- 8.2. Multiple Sessions
-
- For dual sessions the terminal has two serial ports of equal status.
- Each port is connected to a serial port on a different computer. Thus
- one may log in to two different computers with each session displaying
- in a split-screen window. Alternatively, each session may run full-
- screen with a "hot" key (or the like) to switch between sessions. One
- could also connect to two different serial ports on the same computer
- and log in twice (similar to "virtual terminals" at the console). The
- program "screen" will make any ordinary terminal (single session)
- connected to a single computer run two or more "sessions".
-
-
- 8.3. Printer/Auxiliary Port
-
- Many terminals have a connector on the rear for such a port. It may
- be labeled as "Aux" or "Printer", etc. Some printer ports are for
- parallel printers while others are for serial printers. If a printer
- is connected to the printer or auxiliary port, then pressing certain
- keys will print the screen. One may also have everything that
- displays on the screen go also to the printer. If the port is an
- auxiliary port, one may connect this to another computer and almost
- have dual sessions as above. However, the video memory inside the
- terminal may not retain both sessions so you may need to refresh the
- screen when switching to the other session. There will likely not be
- a hot key either but possibly a programmable function key may be
- programmed to do this. There exists various key combinations and
- escape sequences for controlling such a port. See ``Printer Esc''.
-
- There is a program called vtprint which is designed to send a print
- job (text only) to your terminal to be printed on a printer attached
- to the terminal. It's homepage is
- . It's also
- included in the Debian distribution of Linux. xprt (also in Debian)
- seems to do something similar, but only for X Window terminals ??
-
- Using the printer port to print may be useful if you don't have an
- extra port on your PC for a printer or for "point of sale" use in a
- store. "Transparent print mode" is where whatever the PC sends out to
- the terminal goes instead to the printer. If you want the printer to
- be able to send bytes to the PC (in the reverse direction) then (per
- Wyse) it's "bidirectional mode". The Wyse "auxiliary print mode" is
- just transparent print mode where the terminal screen monitors what's
- being printed.
-
-
- 8.4. Pages
-
- Many terminals permit the storage of more than one page in their video
- memory. Sometimes the page size is the same as the screen, but
- sometimes it is larger so that scrolling will reveal unseen parts of a
- page. So when one looks at a screen, there may be hidden text on the
- same page above or below the display. In addition, if there is more
- than just one page, there may be hidden text on these other pages.
- One use for pages is on terminals that support dual sessions. Each
- session may have its own page and one may switch back and forth
- between them.
-
- Even if you only have a one-page-terminal with the page sized equal to
- what is displayed on the screen, you will still see other pages of a
- file (etc.) as the host sends more data to the terminal. One
- advantage to having additional pages stored in the terminal memory is
- so that you can jump to them instantly without waiting a second or so
- for them to be transmitted from the host.
-
- Multiple pages is supported by ncurses. There is also a commercial
- program called "Multiscreen" which supports multiple pages but
- probably not for Linux ?? Multiscreen is reported to be part of SCO
- and is something like the virtual terminals on a Linux PC console.
- The Linux program "screen" makes it look like you have multiple pages
- but they are stored in the computer and but you can have only one
- page-like window for each running program.
-
-
- 8.5. Character-Sets
-
- A character-set is normally represented by a list (or table or chart)
- of characters along with the byte code assigned to each character.
- The codes for a byte range from 0 to 255 (00 to FF in hexadecimal).
- In MS-DOS, character-set tables are called "code-pages". You should
- examine such a table if you're not familiar with them. They are
- sometimes included in printer and terminal manuals but also are found
- on the Internet.
-
- Many character sets include letters from foreign languages. But they
- may also include special characters used to draw boxes and other
- special characters.
-
- ASCII was the traditional English character set used on text terminals
- It is a 7-bit code but will usually work OK even if your terminal is
- set to 8-bit mode. In 8-bit mode with ASCII, the high order bit is
- always set to zero. Other character-sets are usually available and
- usually use 8-bit codes (except on very old terminals where the only
- choice is ASCII). The first half of most character-sets are the
- conventional 128 ASCII characters and the second half (with the high-
- order bit set to 1) belong to a wide variety of character-sets.
- Character sets are often ISO standards. To get specialized character
- sets on a terminal, you may need to download a soft-font for that
- character-set into the memory of the terminal. Many terminals have a
- number of built-in character sets (but perhaps not the one you need).
-
- Here are some common 8-bit character sets. CP stands for Code Page
- character sets invented by IBM: CP-437 (DOS ECS), ISO-8859-1
- (Latin-1), CP-850 (Multilingual Latin 1 --not the same as ISO
- Latin-1), CP-1252 (WinLatin1 = MS-ANSI). MS Windows uses CP-1252
- (WinLatin1) while the Internet often uses Latin-1. There are several
- ISO-8859- character sets in addition to Latin-1. These include Greek
- (-7), Arabic (-6), Eastern European (-2), and a replacement for
- Latin-1 (-15) called Latin-9. There are many others. For example,
- KOI8-R is more commonly used for Russian than IS0-8859-5. Unicode is
- a very large character-set where each character is represented by 2
- bytes instead on just one byte.
-
- More info re character-sets are:
-
- · Manual pages: charsets, iso_8859-l or latin1 (covers 8859 series),
- ascii
-
- · HOWTO's for various languages (often written in that language).
-
- · ISO-8859 Alphabet Soup
- More than just iso8859. Extensive.
-
- · A tutorial on character code issues
- Clearly written.
-
- · Languages, Countries and Character Sets
-
-
- · Languages of the World by Computers ...
-
-
- · Links re Internationalization
- A long list of
- links (in Russian but most words in English).
-
- · ... International Character Sets
-
-
- Once you've found the character set name (or alpha-numeric
- designation) you are interested in, you may search for more info about
- it on the Internet.
-
-
- 8.5.1. Graphics (Line Drawing, etc.)
-
- There are special characters for drawing boxes, etc. There are also
- numerous non-ASCII symbols such as bullets. These may either be part
- of an 8-bit character set (such as WinLatin1 = CP-1252) or provided as
- a separate font (in vt100 terminals). Your terminfo may be set up to
- use them. But if you see a row of letters when there should be a
- line, it may mean that terminfo hasn't implemented them.
-
- You need to know the following if your graphics don't work right. The
- default graphic character set is the vt-100 ANSI graphics. Otherwise
- the string acsc must be defined in your terminfo. It establishes a
- map between the vt-100 graphic characters codes and the actual codes
- used on your terminal. So even if your terminal doesn't have the
- vt-100 graphics, it can likely still generate such graphics with some
- other character set. If terminfo has it right, this will happen
- automatically.
-
- If character sets must be switched then the terminfo variables: enacs,
- rmacs, and smacs should be defined. Note acs = Alternate Character
- Set. Even if the upper half of the normal character set contains the
- graphic characters it may be considered a separate 7-bit character set
- that needs to be switched to.
-
-
- 8.5.2. National Replacement Characters (obsolete)
-
- These result in modified 7-bit ASCII codes. They became obsolete in
- the 1990's but exist on some older terminals. Many West-European
- languages only need several additional letters which are not in ASCII.
- To get them in 7-bit code, one may borrow the codes for seldom used
- ASCII symbols:
- The symbols $ and # are sometimes used also. So when using these
- replacement character sets, you are deprived of using certain ASCII
- symbols since they now are used for the new non-ASCII letters. Now
- that 8-bit character codes have mostly replaced 7-bit ones, it's
- better to use an 8-bit code which has both all the ASCII symbols plus
- the non-ASCII characters for various languages.
-
- ISO-646 (for 1972 and later) permits using National Replacement
- Characters (7-bit). It specifies that the above mentioned character
- codes may be borrowed, but doesn't specify which national characters
- are to replace them. Some countries standardized the replacements by
- registering them with ECMA.
-
- Many terminals exist which support these national replacement
- characters but you probably don't want to implement them unless you
- have some old files to read. Very old terminals may only support one
- language (for the country in which they were sold). Later terminals
- offered a choice of languages. Modem terminals are 8-bit and don't
- need "national replacements". Replacement characters exist for the
- following languages/countries: British, Cuba (Spanish), Dutch,
- Finnish, French, French Canadian, German, Hebrew, Hungarian, Italian,
- Norwegian/Danish, Portuguese, Spanish, Swedish, Swiss (German).
-
- Here's tables for some character sets taken from Kermit and Unisys
- documents:
-
-
-
- Swedish Danish
- ASCII German Finnish Norwegian French
-
- @ at-sign section ------- ------- a-grave
- [ left-bracket A-diaeresis A-diaeresis AE-digraph degree
- / backslash O-diaeresis O-diaeresis O-slash c-cedilla
- ] right-bracket U-diaeresis A-circle A-circle section
- ^ circumflex ------ U-diaeresis ------- -------
- ` accent-grave ------ e-acute ------- -------
- { left-brace a-diaeresis a-diaeresis ae-digraph e-acute
- | vertical-bar o-diaeresis o-diaeresis o-circle u-grave
- } right-brace u-diaeresis a-circle a-circle e-grave
- ~ tilde ess-zet u-diaeresis -------- diaeresis
-
- ASCII Italian Spanish
-
- @ at-sign section section
- [ left-bracket degree inverted-exclamation
- / backslash #-pound N-tilde
- ] right-bracket e-acute inverted-question-mark
- ^ circumflex ------- -------
- ` accent-grave u-grave -------
- { left-brace a-grave degree
- | vertical-bar o-grave n-tilde
- } right-brace e-grave --------
- ~ tilde i-grave --------
-
-
-
- 8.6. Fonts
-
- Most terminals made after the mid 1980's can accept downloaded soft-
- font. This means that they can display almost any character set
- provided that you can find the soft-font for it. If you can't find
- the needed soft-font, you can always create your own. A free font
- editor for this is called BitFontEdit (written by the author of this
- document) and (in 1998) was at
- Europe:
- N. America: For
- mapping the keyboard (and screen) for use of various fonts see
- ``Character Mapping: mapchan''
-
-
- 8.7. Keyboards & Special Keys
-
- Terminal keyboards often have a number of keys that one doesn't find
- on a PC keyboard. Few (if any) actual terminals will have all of
- these keys and most will have additional keys not listed here. Some
- have a large number of special purpose keys such as terminals made for
- use with cash registers. There are often many more key meanings than
- shown here since these keys often have extended meanings when used in
- conjunction with other keys (such as shift and control).
-
-
- · BREAK sends a very long 0 bit (space = +12 V) of duration 300 to
- 700 milliseconds to the host. The host may interpret this as an
- interrupt if stty has set brkint or ignore it if ignbrk is set.
-
- · NO SCROLL stops the screen from scrolling like ^S does. Depressing
- it again resumes scrolling. Uses flow control signals to do this.
-
- · REPEAT if held down with an other key, forces repeated output of
- that other key even if the auto-repeat option is set to off.
-
- · LINE FEED sends the line feed character ^J to the host. Seldom
- used.
-
- · SET-UP allows the manual configuration of the terminal via menus.
- Sometimes purposely disabled by putting a block under it so it
- can't be pressed down. Sometimes another key such as shift or
- control must be pressed at the same time. See ``Getting Into Set-Up
- (Configuration) Mode''.
-
- · LOCAL disconnects the terminal from the host. In local, what one
- types goes directly to the screen. Useful for testing.
-
- · RETURN is the same as the "enter" key on a PC. It usually sends a
- carriage return to the host which normally get translated to a new-
- line character by the host's device driver. On some terminals it
- may be set up to send something else.
-
- · F1, F2, ... or PF1, PF2, ... are function keys which usually may be
- programmed to send out a sequence of bytes (characters). See
- ``Function Keys''
-
-
- 8.8. Mouse
-
- A few text-terminals support a mouse. When the mouse is clicked, an
- escape sequence is sent to the host to tell it where the mouse is.
- For a mouse on VT terminals see
- These
- escape codes for mice are called "DEC Locator sequences". The FALCO
- Infinity Series of terminals, model ANSI-G supports it. Do any linux
- applications support this ??
-
-
-
- 9. Terminal Emulation (including the Console)
-
- 9.1. Intro to Terminal Emulation
-
- Since a PC has a screen and keyboard (as does a terminal) but also has
- much more computing power, it's easy to use some of this computing
- power to make the PC computer behave like a text terminal. This is
- one type of terminal emulation. Another type of terminal emulation is
- where you set up a real terminal to emulate another brand/model of
- terminal. To do this you select the emulation you want (called
- "personality" in Wyse jargon) from the terminal's set-up menu. This
- section is about the first type of emulation: emulating a terminal on
- a PC.
-
- In emulation, one of the serial ports of the computer will be used to
- connect the emulated terminal to another computer, either with a
- direct cable connection from serial port to serial port, or via a
- modem. Emulation provides more that just a terminal since the PC
- doing the emulation can also do other tasks at the same time it's
- emulating a terminal. For example, kermit or zmodem may be run on the
- PC to enable transfer of files over the serial line (and possibly over
- the phone line via a modem) to the other computer that you are
- connected to. The emulation needs only to be run on one of the
- virtual consoles of the PC, leaving the other virtual consoles
- available for using the PC in command-line-interface.
-
- Much emulation software is available for use under the MS Windows OS.
- See ``Make a non-Linux PC a terminal'' This can be used to connect a
- Windows PC to a Linux PC (as a Text-Terminal). Most Linux free
- software can only emulate a VT100, VT102, or VT100/ANSI. If you find
- out about any others, let me know. Since most PC's have color
- monitors while VT100 and VT102 were designed for a monochrome monitor,
- the emulation usually adds color capabilities (including a choice of
- colors). Sometimes the emulation is not 100% perfect but this usually
- causes few problems. For using a Mac computer to emulate a terminal
- see the mini-howto: Mac-Terminal.
-
-
- 9.2. Don't Try to Use TERM Variable for Emulation
-
- Some have erroneously thought that they could create an emulator at a
- Linux console (monitor) by setting the environment variable TERM to
- the type of terminal they would like to emulate. This does not work.
- The value of TERM only tells an application program what terminal you
- are using. This way it doesn't need to interactively ask you this
- question. If you're at a Linux PC monitor (command line interface)
- it's a terminal of type "Linux" and your can't change this. So you
- must set TERM to "Linux".
-
- If you set it to something else you are fibbing to application
- programs. As a result they will incorrectly interpret certain escape
- sequences from the console resulting in a corrupted interface. Since
- the Linux console behaves almost like a vt100 terminal, it could still
- work almost OK if you falsely claimed it was a vt100 (or some other
- terminal which is something like a vt100). It may seeming work OK
- most of the time but once in a while will make a mistake when editing
- or the like.
-
-
- 9.3. Communication (Dialing) programs
-
- Dialing programs for making a PPP connection to the Internet don't
- normally include any terminal emulation. But some other modem dialing
- programs (such as minicom or seyon) do. Using them, one may (for
- example) dial up some public libraries to use their catalogs and
- indexes, (or even read magazine articles). They are also useful for
- testing modems. Seyon is only for use with X Window and can emulate
- Tektronix 4014 terminals.
-
- The communication program Kermit doesn't do terminal emulation as it
- is merely a semi-transparent pipe between whatever terminal you are on
- and the remote site you are connected to. Thus if you use kermit on a
- Linux PC the terminal type will be "Linux". If you have a Wyse60
- connected to your PC and run kermit on that, you will appear as a
- Wyse60 to the remote computer (which may not be able to handle Wyse60
- terminals). Minicom emulates a VT102 and if you use it on Wyse60
- terminal VT102 escape sequences coming into your computer's serial
- port from a remote computer will get translated to the Wyse escape
- sequences before going out another serial port to your Wyse60
- terminal. Kermit can't do this sort of thing.
-
- Emulators exist under DOS such as telix and procomm work just as well.
- The terminal emulated is often the old VT100, VT102, or ANSI (like
- VT100).
-
-
- 9.3.1. Emulation under X Window
-
- Xterm (or uxterm which is like xterm except it supports unicode) may
- be run under X Window. They can emulate a VT102, VT220, or Tektronix
- 4014. There is also an xterm emulation (although there is no physical
- terminal named "xterm"). If you don't need the Tektronix 4014
- emulation (a vector graphics terminal; see ``Graphics Terminals'') you
- may use eterm. Predecessors to eterm are rxvt and xvt. eterm
- supports pixmaps.
-
- For non-Latin alphabets, kterm is for Kanji terminal emulation (or for
- other non-Latin alphabets) while xcin is for Chinese. There is also
- 9term emulation. This seems to be more than just an emulator as it
- has a built-in editor and scroll-bars. It was designed for Plan 9, a
- Unix-like operating system from AT&T.
-
-
- 9.3.2. Real terminals better
-
- Unless you are using X Window with a large display, a real terminal is
- often nicer to use than emulating one. It usually has better
- resolution for text, and has no disk drives to make annoying noises.
-
-
- 9.4. Testing Terminal Emulation
-
- For the VT series terminals there is a test program: vttest to help
- determine if a terminal behaves correctly like a vt53, vt100, vt102,
- vt220, vt320, vt420 etc. There is no documentation but it has menus
- and is easy to use. To compile it run the configure script and then
- type "make". It may be downloaded from:
-
-
-
- 9.5. The Linux Console
-
- The console for a PC Linux system is normally the computer monitor in
- text mode. It emulates a terminal of type "Linux" and the escape
- sequences it uses are in the man page: console_codes. There is no way
- (unless you want to spend weeks rewriting the kernel code) to get it
- to emulate anything else. Setting the TERM environment variable to
- any type of terminal other than "Linux" will not result in emulating
- that other terminal. It will only result in a corrupted interface
- since you have falsely declared (via the TERM variable) that your
- "terminal" is of a type different from what it actually is. See
- ``Don't Use TERM For Emulation''
- In some cases, the console for a Linux PC is a text-terminal. One may
- recompile Linux to make a terminal receive most of the messages which
- normally go to the console. See ``Make a Serial Terminal the
- Console''.
-
- The "Linux" emulation of the monitor is flexible and has features
- which go well beyond those of the vt102 terminal which it was intended
- to emulate. These include the ability to use custom fonts and easily
- re-map the keyboard. These extra features reside in the console
- driver software (including the keyboard driver). The console driver
- only works for the monitor and will not work for a real terminal even
- if it's being used for the console. Thus the "console driver" is
- really a "monitor driver". In the early days of Linux one couldn't
- use a real terminal as the console so "monitor" and "console" were
- once always the same thing.
-
- The stty commands work for the monitor-console just like it was a real
- terminal. They are handled by the same terminal driver that is used
- for real terminals. Bytes headed for the screen first go thru the
- terminal (tty) driver and then thru the console driver. For the
- monitor some of the stty commands don't do anything (such as setting
- the baud rate). You may set the monitor baud rate to any allowed
- value (such as a slow 300 speed) but the actual speed of putting text
- on the monitor screen will not actually change. The file
- /etc/ioctl.save stores stty settings for use only when the console is
- in single user mode (but you are normally in multiuser-user mode).
- This is explained (a little) in the init man page.
-
- Many commands exist to utilize the added features provided by the
- console-monitor driver. Real terminals, which use neither scan codes
- nor VGA cards, unfortunately can't use these features. To find out
- more about the console see the Keyboard-and-Console-HOWTO. Also see
- the various man pages about the console (type "man -k console").
- Unfortunately, much of this documentation is outdated.
-
-
- 9.6. Emulation Software
-
- Emulators often don't work quite right so before purchasing software
- you should try to throughly check out what you will get.
-
-
- 9.6.1. Make a Linux PC a terminal
-
- Unless you want to emulate the standard vt100 (or close to it) or a
- Wyse 60, there doesn't seem to be much free terminal emulation
- software available for Linux. The free programs minicom and seyon
- (only for X Window) can emulate a vt100 (or close to it). Seyon can
- also emulate a Tektronix 4014 terminal. See Wyse 60 emulator
-
-
- Minicom may be used to emulate a directly connected terminal by simply
- starting minicom (after configuring it for the serial port used). Of
- course, you don't dial out and when you want to quit (after you logout
- from the other PC) you use minicom's q command to quit without reset
- since there is no modem to reset. When minicom starts, it
- automatically sends out a modem init string to the serial port. But
- since there's no modem there, the string gets put after the "login:"
- prompt. If this string is mostly capital letters, the getty program
- (which runs login) at the other PC may think that your terminal has
- only capital letters and try to use only capital letters. To avoid
- this, configure the modem init strings sent by minicom to null (erase
- the init strings).
-
- The terminal emulator "Procomm" (which is from Dos), can be used on a
- Linux PC if you run dosemu to emulate Dos. For details see:
- .
-
- There's a specialized Linux distribution: Serial Terminal Linux. It
- will turn a PC to into a minicom-like terminal. It's small (fits on a
- floppy) and will not let you use the PC for any other purpose (when
- it's running). See .
- It will let you have more than one session running (similar to virtual
- terminals), one for each serial port you have.
-
- TERM (non-free commercial software from Century Software)
- can emulate Wyse60, 50;
- VT 220, 102, 100, 52: TV950, 925, 912; PCTERM; ANSI; IBM3101; ADM-1l;
- WANG 2110. Block mode is available for IBM and Wyse. It runs on a
- Linux PC.
-
-
- 9.6.2. Make a non-Linux PC a terminal
-
- Emulators exist which run on non-Linux PCs. They permit you to use a
- non-Linux-PC as a terminal connected to a Linux-PC. Under DOS there
- is telix and procomm. Windows comes with "HyperTerminal" (formerly
- simply called "Terminal" in Windows 3.x and DOS). Competing with this
- is "HyperTerminal Private Edition"
- which is non-free to
- business. It can emulate vt-220. The Windows "terminals" are
- intended for calling out with a modem but they should also work as
- directly connected terminals?? Turbosoft's TTWin can emulate over 80
- different terminals under Windows. See or
- (Australia). See also Reflection
-
-
- For the Mac Computer there is emulation by Carnation Software
-
-
- One place to check terminal emulation products is Shuford's site, but
- it seems to lists old products (which may still work OK). The fact
- that most only run under DOS (and not Windows) indicates that this
- info is dated. See
- .
-
-
- 10. Flow Control (Handshaking)
-
- Flow control (= handshaking = pacing) is to prevent too fast of a
- flow of bytes from overrunning a terminal, computer, modem or other
- device. Overrunning is when a device can't process what it is
- receiving quickly enough and thus loses bytes and/or makes other
- serious errors. What flow control does is to halt the flow of bytes
- until the terminal (for example) is ready for some more bytes. Flow
- control sends its signal to halt the flow in a direction opposite to
- the flow of bytes it wants to stop. Flow control must both be set at
- the terminal and at the computer.
-
- There are 2 types of flow control: hardware and software (Xon/Xoff or
- DC1/DC3). Hardware flow control uses dedicated signal wires such as
- RTS/CTS or DTR/DSR while software flow control signals by sending DC1
- or DC3 control bytes in the normal data wires. For hardware flow
- control, the cable must be correctly wired.
-
- The flow of data bytes in the cable between 2 serial ports is bi-
- directional so there are 2 different flows (and wires) to consider:
-
- 1. Byte flow from the computer to the terminal
-
- 2. Byte flow from the terminal keyboard to the computer.
-
- 10.1. Why Is Flow Control Needed ?
-
- You might ask: "Why not send at a speed slow enough so that the device
- will not be overrun and then flow control is not needed?" This is
- possible but it's usually significantly slower than sending faster and
- using flow control. One reason for this is that one can't just set
- the serial port baud rate at any desired speed such as 14,500, since
- only a discrete number of choices are available. The best choice is
- to select a rate that is a little higher than the device can keep up
- with but then use flow control to make things work right.
-
- If one decides to not use flow control, then the speed must be set low
- enough to cope with the worst case situation. For a terminal, this is
- when one sends escape sequences to it to do complex tasks that take
- more time than normal. In the case of a modem (with data compression
- but no flow control) the speed from the computer to the modem must be
- slow enough so that this same speed is usable on the phone line, since
- in the worst case the data is random and can't be compressed. If one
- failed to use flow control, the speed (with data compression turned
- on) would be no faster than without using any compression at all.
-
- Buffers are of some help in handling worst case situations of short
- duration. The buffer stores bytes that come in too fast to be
- processed at once, and saves them for processing later.
-
-
- 10.2. Padding
-
- Another way to handle a "worst case" situation (without using flow
- control or buffers) is to add a bunch of nulls (bytes of value zero)
- to escape sequences. Sometimes DEL's are used instead provided they
- have no other function. See ``Recognize Del''.
-
- The escape sequence starts the terminal doing something, and while the
- terminal is busy doing it, it receives a bunch of nulls which it
- ignores. When it gets the last null, it has completed its task and is
- ready for the next command. This is called null padding. These nulls
- formerly were called "fill characters". These nulls are added just to
- "waste" time, but it's not all wasted since the terminal is usually
- kept busy doing something else while the nulls are being received. It
- was much used in the past before flow control became popular. To be
- efficient, just the right amount of nulls should be added and figuring
- out this is tedious. It was often done by trial and error since
- terminal manuals are of little or no help. If flow control doesn't
- work right or is not implemented, padding is one solution. Some of
- the options to the stty command involve padding.
-
-
- 10.3. Overrunning a Serial Port
-
- One might wonder how overrunning is possible at a serial port since
- both the sending and receiving serial ports involved in a transmission
- of data bytes are set for the same speed (in bits/sec) such as 19,200.
- The reason is that although the receiving serial port electronics can
- handle the incoming flow rate, the hardware/software that fetches and
- processes the bytes from the serial port sometimes can't cope with the
- high flow rate.
-
- One cause of this is that the serial port's hardware buffer is quite
- small. Older serial ports had a hardware buffer size of only one byte
- (inside the UART chip). If that one received byte of data in the
- buffer is not removed (fetched) by CPU instructions before the next
- byte arrives, that byte is lost (the buffer is overrun). Newer
- UART's, namely most 16550's, have 16-byte buffers (but may be set to
- emulate a one-byte buffer) and are less likely to overrun. It may be
- set to issue an interrupt when the number of bytes in its buffer
- reaches 1, 4, 8, or 14 bytes. It's the job of another computer chip
- (usually the main CPU chip for a computer) to take these incoming
- bytes out of this small hardware buffer and process them (as well as
- perform other tasks).
-
- When contents of this small hardware receive buffer reaches the
- specified limit (one byte for old UART'S) an interrupt is issued.
- Then the computer interrupts what it was doing and software checks to
- find out what happened. It finally determines that it needs to fetch
- a byte (or more) from the serial port's buffer. It takes these
- byte(s) and puts them into a larger buffer (also a serial port buffer)
- that the kernel maintains in main memory. For the transmit buffer,
- the serial hardware issues an interrupt when the buffer is empty (or
- nearly so) to tell the CPU to put some more bytes into it to send out.
-
- Terminals also have serial ports and buffers similar to the computer.
- Since the flow rate of bytes to the terminal is usually much greater
- than the flow in the reverse direction from the keyboard to the host
- computer, it's the terminal that is most likely to suffer overrunning.
- Of course, if you're using a computer as a terminal (by emulation),
- then it is likewise subject to overrunning.
-
- Risky situations where overrunning is more likely are: 1. When
- another process has disabled interrupts (for a computer). 2. When the
- serial port buffer in main (or terminal) memory is about to overflow.
-
-
- 10.4. Stop Sending
-
- When its appears that the receiver is about to be overwhelmed by
- incoming bytes, it sends a signal to the sender to stop sending. That
- is flow control and the flow control signals are always sent in a
- direction opposite to the flow of data which they control (although
- not in the same channel or wire). This signal may either be a control
- character (^S = DC3 = Xoff) sent as an ordinary data byte on the data
- wire (in-band signalling), or a voltage transition from positive to
- negative in the dtr-to-cts (or other) signal wire (out-of-band
- signalling). Using Xoff is called "software flow control" and using
- the voltage transition in a dedicated signal wire (inside the cable)
- is called hardware flow control.
-
-
- 10.5. Keyboard Lock
-
- With terminals, the most common case of "stop sending" is where the
- terminal can't keep up with the characters being sent to it and it
- issues a "stop" to the PC. Another case of this is where someone
- presses control-S. Much less common is the opposite case where the PC
- can't keep up with your typing speed and tells the terminal to stop
- sending. The terminal "locks" its keyboard and a message or light
- should inform you of this. Anything you type at a locked keyboard is
- ignored. When the PC catches up on it's work, then the keyboard
- should unlock. When it doesn't, there is likely some sort of deadlock
- going on.
-
- Another type of keyboard lock happens when a certain escape sequence
- (or just the ^O control character for Wyse 60) is sent to the
- terminal. While the previous type of lock is done by the serial
- driver, this type of lock is done by the hardware of a real terminal.
- It's a catch-22 situation if this happens since you can't type any
- commands to escape out of this lock. Going into setup and resetting
- might work (but it failed on my Wyse 60 and I had to cycle power to
- escape). One could also send an "unlock keyboard" escape sequence
- from another terminal.
-
-
- The term "locked" is also sometimes used for the common case of where
- the computer is told to stop sending to a terminal. The keyboard is
- not locked so that whatever you type goes to the computer. Since the
- computer can't send anything back to you, characters you type don't
- display on the screen and it may seem like the keyboard is locked.
- Scrolling is locked (scroll lock) but the keyboard is not locked.
-
-
- 10.6. Resume Sending
-
- When the receiver has caught up with its processing and is ready to
- receive more data bytes it signals the sender. For software flow
- control this signal is the control character ^Q = DC1 = Xon which is
- sent on the regular data line. For hardware flow control the voltage
- in a signal line goes from negative (negated) to positive (asserted).
- If a terminal is told to resume sending the keyboard is then unlocked
- and ready to use.
-
-
- 10.7. Hardware Flow Control (RTS/CTS etc.)
-
- Some older terminals have no hardware flow control while others used a
- wide assortment of different pins on the serial port for this. For a
- list of various pins and their names see ``Standard Null Modem Cable
- Pin-out''. The most popular pin to use seems to be the DTR pin (or
- both the DTR pin and the DSR pin).
-
-
- 10.7.1. RTS/CTS, DTR, and DTR/DSR Flow Control
-
- Linux PC's use RTS/CTS flow control, but DTR/DSR flow control (used by
- some terminals) behaves similarly. DTR flow control (in one direction
- only and also used by some terminals) is only the DTR part of DTR/DSR
- flow control.
-
- RTS/CTS uses the pins RTS and CTS on the serial (EIA-232) connector.
- RTS means "Request To Send". When this pin stays asserted (positive
- voltage) at the receiver it means: keep sending data to me. If RTS is
- negated (voltage goes negative) it negates "Request To Send" which
- means: request not to send to me (stop sending). When the receiver is
- ready for more input, it asserts RTS requesting the other side to
- resume sending. For computers and terminals (both DTE type equipment)
- the RTS pin sends the flow control signal to the CTS pin (Clear To
- Send) on the other end of the cable. That is, the RTS pin on one end
- of the cable is connected to the CTS pin at the other end.
-
- For a modem (DCE equipment) it's a different scheme since the modem's
- RTS pin receives the signal and its CTS pin sends. While this may
- seem confusing, there are valid historical reasons for this which are
- too involved to discuss here.
-
- Terminals usually have either DTR or DTR/DSR flow control. DTR flow
- control is the same as DTR/DSR flow control but it's only one-way and
- the DSR pin is not used. For DTR/DSR flow control at a terminal, the
- DTR signal is like the signal sent from the RTS pin and the DSR pin is
- just like the CTS pin.
-
-
- 10.7.2. Connecting up DTR or DTR/DSR Flow Control
-
- Some terminals use only DTR flow control. This is only one-way flow
- control to keep the terminal from being overrun. It doesn't protect
- the computer from someone typing too fast for the computer to handle
- it. In a standard null modem (crossover) cable the DTR pin at the
- terminal is connected to the DSR pin at the computer. But Linux
- doesn't support DTR/DSR flow control (although drivers for some
- multiport boards may support DTR/DSR flow control.) A way around this
- problem is to simply wire the DTR pin at the terminal to connect to
- the CTS pin at the computer and set RTS/CTS flow control (stty
- crtscts). The fact that it's only one way will not affect anything so
- long as the host doesn't get overwhelmed by your typing speed and drop
- RTS in a vain attempt to lock your keyboard. See ``Keyboard Lock''.
- For DTR/DSR flow control (if your terminal supports this two-way flow
- control) you do the above. But you also connect the DSR pin at the
- terminal to the RTS pin at the computer. Then you are protected if
- you type too fast.
-
-
- 10.7.3. Old RTS/CTS handshaking is different
-
- What is confusing is that there is the original use of RTS where it
- means about the opposite of the previous explanation above. This
- original meaning is: I Request To Send to you. This request was
- intended to be sent from a terminal (or computer) to a modem which, if
- it decided to grant the request, would send back an asserted CTS from
- its CTS pin to the CTS pin of the computer: You are Cleared To Send to
- me. Note that in contrast to the modern RTS/CTS bi-directional flow
- control, this only protects the flow in one direction: from the
- computer (or terminal) to the modem.
-
- For older terminals, RTS may have this meaning and goes high when the
- terminal has data to send out. The above use is a form of flow
- control since if the modem wants the computer to stop sending it drops
- CTS (connected to CTS at the computer) and the computer stops sending.
-
-
- 10.7.4. Reverse Channel
-
- Old hard-copy terminals may have a reverse channel pin (such as pin
- 19) which behaves like the RTS pin in RTS/CTS flow control. This pin
- but will also be negated if paper or ribbon runs out. It's often
- feasible to connect this pin to the CTS pin of the host computer.
- There may be a dip switch to set the polarity of this signal.
-
-
- 10.8. Is Hardware Flow Control Done by Hardware ?
-
- Some think that hardware flow control is done by hardware but only a
- small part of it is done by hardware. Most of it is actually done by
- your operating system software. UART chips and associated hardware
- usually know nothing at all about hardware flow control. When a
- hardware flow control signal is received (due to the signal wire
- flipping polarity) the hardware gives an electrical interrupt signal
- to the CPU. However, the hardware has no idea what this interrupt
- means. The CPU stops what it was doing and jumps to a table in main
- memory that tells the CPU where to go to find a program which will
- find out what happened and determine what to do about it. In this
- case this program stops the outgoing flow of bytes.
-
- But even before this program stops the flow, it was already stopped
- by the interrupt which interrupted the work of the CPU. This is one
- reason why hardware flow control stops the flow faster. It doesn't
- need to wait for a program to do it. But if that program didn't
- command that the flow be stopped, the flow would resume once that
- program exited. So the program is essential to stop the flow even
- though it is not the first to actually stop the flow. After the
- interrupt happens any bytes (up to 16) which were already in the
- serial port's hardware transmit buffer will still get transmitted. So
- even with hardware flow control the flow doesn't instantly stop.
-
- Using software flow control requires that each incoming byte be
- checked to see if it's an "off" byte. These bytes are delayed by
- passing thru the 16-byte receive buffer. If the "off" byte was the
- first byte into this buffer, there could be a wait while 15 more bytes
- were received. Then the 16 bytes would get read and the "off" byte
- found. This extra delay doesn't happen with hardware flow control.
-
-
- 10.9. Obsolete ?? ETX/ACK or ENQ/ACK Flow Control
-
- This is also software flow control and requires a device driver that
- knows about it. Bytes are sent in packets (via the async serial port)
- with each packet terminated by an ETX (End of Text) control character.
- When the terminal gets an ETX it waits till it is ready to receive the
- next packet and then returns an ACK (Acknowledge). When the computer
- gets the ACK, it then send the next packet. And so on. This is not
- supported by Linux ?? Some HP terminals use the same scheme but use
- ENQ instead of ETX.
-
-
- 11. Physical Connection
-
- 11.1. Introduction
-
- A terminal may be connected to its host computer either by a direct
- cable connection, via a modem, or via a terminal server. The flow of
- data may be either a direct sequence of bytes (such as from a serial
- port) or packets on a network (such as TCP/IP).
-
-
- 11.2. Multiport I/O Cards (Adapters)
-
- Additional serial cards may be purchased which have many serial ports
- on them called "multiport boards". These boards are not covered in
- this HOWTO but there is a list of some of them (with URLs) in the
- Serial-HOWTO.
-
-
- 11.3. Direct Serial Cable Connection.
-
- The simplest way to connect a terminal to a host computer is via a
- direct connection to a serial port on the computer. You may also use
- some the info in this section for connecting one computer to another
- (via the serial port). Most PC's come with a couple of serial ports,
- but one is usually used by a mouse. For the EIA-232 port, you need a
- null modem cable that crosses over the transmit and receive wires. In
- ethernet terminology it would be called a "crossover cable" (but the
- ethernet cable will not work for the serial port). If you want
- hardware flow control, you will probably use the DTR pin (or both the
- DTR and DSR pins).
-
- Make sure you have the right kind of cable. A null modem cable bought
- at a computer store may do it (if it's long enough), but it probably
- will not work for hardware flow control. Such a cable may be labeled
- as a serial printer cable. Only larger computer stores are likely to
- stock such cables. A "modem cable" will not work since the wires go
- straight thru (and don't cross over). See ``Buy or Make'' your own
- cable. Make sure you are connecting to your PC's serial port at the
- male DB25 or the DB9, and not to your parallel port (female DB25).
-
-
- 11.3.1. Pin numbering
-
- Pin numbers are often printed on the plastic right next to the pins.
- You may need a bright light and/or a magnifying glass to read them.
- Looking at the male pins of a DB connector with the wider row up, the
- pin in the upper left is 1 (there is no pin 0). Then the next pin in
- this row is 2, etc. At the end of this row is pin 5 or 13. Then the
- next pin (6 or 14) is in the next row all the way to the left and
- below pin 1. If you look at the female connector with the wider row
- up, then pin 1 is in the upper right corner.
-
-
- 11.3.2. Null Modem cable pin-out (3, 4, or 5 conductor)
-
- These 3 diagrams are for real text-terminals. But you could use them
- to connect up 2 PCs if you substitute RTS for DTR and CTS for DSR.
- (Don't use 4-conductors for PC-to-PC). For terminals, if you only
- have DTR flow control (one-way) you may eliminate the RTS-to-DSR wire.
- If you have no hardware flow control, then you may also eliminate the
- CTS-to-DTR wire. Then if you have 2@ twisted pairs, you may then use
- 2 wires for signal ground per ``A Kludge using Twisted-Pair Cable''.
- For a DB25 connector on your PC, you need:
-
-
-
- PC male DB25 Terminal DB25
- TxD Transmit Data 2 --> 3 RxD Receive Data
- RxD Receive Data 3 <-- 2 TxD Transmit Data
- SG Signal Ground 7 --- 7 SG Signal Ground
- CTS Clear To Send 5 <--20 DTR Data Terminal Ready
- RTS Request To Send 4 --> 6 DSR Data Set Ready
-
-
-
- If you have a DB9 connector on your PC, try the following:
-
-
- PC DB9 Terminal DB25
- RxD Receive Data 2 <-- 2 TxD Transmit Data
- TxD Transmit Data 3 --> 3 RxD Receive Data
- SG Signal Ground 5 --- 7 SG Signal Ground
- CTS Clear To Send 8 <--20 DTR Data Terminal Ready
- RTS Request To Send 7 --> 6 DSR Data Set Ready **
-
-
-
- If you have a DB9 connector on both your serial port and terminal:
-
-
- PC DB9 Terminal DB9
- RxD Receive Data 2 <-- 3 TxD Transmit Data
- TxD Transmit Data 3 --> 2 RxD Receive Data
- SG Signal Ground 5 --- 5 SG Signal Ground
- CTS Clear To Send 8 <-- 4 DTR Data Terminal Ready
- RTS Request To Send 7 --> 6 DSR Data Set Ready **
-
-
-
- The above don't have modem control lines so be sure to give a "local"
- option to getty (which is equivalent to "stty clocal"). Also if you
- need hardware flow control it must be enabled at your computer (use a
- -h flag with agetty) ( equivalent to "stty crtscts" ).
-
-
- 11.3.3. Standard Null Modem cable pin-out (7 conductor)
-
- The following 3 diagrams show full "standard" null modem cables. One
- that you purchase may be wired this way. Another pinout is for 20 and
- 6 to cross over and to have 8 cross over to both 4 and 5. This will
- not provide hardware flow control (RTS/CTS) for directly connected
- computers. Both of the above will work for terminals using software
- (Xon/Xoff) flow control (or no flow control). None of these cables
- will work for terminal hardware flow control since most real terminals
- support DTR or DTR/DSR flow control (handshaking) but Linux doesn't
- yet (2000).
-
-
-
- PC male DB25 Terminal DB25
- DSR Data Set Ready 6 <--|
- DCD Carrier Detect 8 <--|- 20 DTR Data Terminal Ready
- TxD Transmit Data 2 ----> 3 RxD Receive Data
- RxD Receive Data 3 <---- 2 TxD Transmit Data
- RTS Request To Send 4 ----> 5 CTS Clear To Send
- CTS Clear To Send 5 <---- 4 RTS Request To Send
- SG Signal Ground 7 ----- 7 SG Signal Ground
- DTR Data Terminal Ready 20 -|--> 8 DCD Carrier Detect
- |--> 6 DSR Data Set Ready
-
-
-
- Alternatively, a full DB9-DB25 null modem cable (will not work with
- terminal hardware handshaking; see above):
-
-
- PC DB9 Terminal DB25
- RxD Receive Data 2 <---- 2 TxD Transmit Data
- TxD Transmit Data 3 ----> 3 RxD Receive Data
- |--> 6 DSR Data Set Ready
- DTR Data Terminal Ready 4 -|--> 8 DCD Carrier Detect
- SG Signal Ground 5 ----- 7 SG Signal Ground
- DCD Carrier Detect 1 <--|
- DSR Data Set Ready 6 <--|- 20 DTR Data Terminal Ready
- RTS Request To Send 7 ----> 5 CTS Clear To Send
- CTS Clear To Send 8 <---- 4 RTS Request To Send
- RI Ring Indicator 9 (not needed)
-
-
-
- (Yes, the pins 2 and 3 really do have opposite meanings for DB9 and
- DB25 connectors!)
-
- Here's how to null-modem connect two DB9's together (but DTR flow
- control will not work):
-
-
- PC DB9 DB9
- RxD Receive Data 2 <----- 3 TxD Transmit Data
- TxD Transmit Data 3 -----> 2 RxD Receive Data
- |--> 6 DSR Data Set Ready
- DTR Data Terminal Ready 4 --|--> 1 DCD Carrier Detect
- GND Signal Ground 5 ------ 5 GND Signal Ground
- DCD Carrier Detect 1 <--|
- DSR Data Set Ready 6 <--|-- 4 DTR Data Terminal Ready
- RTS Request To Send 7 -----> 8 CTS Clear To Send
- CTS Clear To Send 8 <----- 7 RTS Request To Send
- RI Ring Indicator 9 (not used)
-
-
-
- Using the above 2 connections provide full modem control signals and
- seemingly allow one to set "stty -clocal". Then one must turn on the
- terminal first (asserts DTR) before the port may be opened in a normal
- manner by getty, etc. But there is likely to be trouble if you fail
- to turn on the terminal first (see ``Getty Respawning Too Rapidly'').
- For this reason one should use "stty clocal" which is the default
- (ignores modem control lines) and the additional wires in these cables
- then serve no useful purpose.
-
- In olden days when it may not have been this easy to ignore modem
- control signals etc, the following "trick" was done for cables that
- lacked conductors for modem control: on your computer side of the
- connector, connect RTS and CTS together, and also connect DSR, DCD and
- DTR together. This way, when the computer needs a certain handshaking
- signal to proceed, it will get it (falsely) from itself.
-
-
- 11.3.4. Overcoming length limitations
-
- A cable longer than a 50 feet or so may not work properly at high
- speed. Much longer lengths sometimes work OK, especially if the speed
- is low and/or the cable is a special low-capacitance type and/or the
- electronics of the receiving end are extra sensitive. It is claimed
- that under ideal conditions at 9600 baud, 1000 feet works OK. One way
- to cover long distances is to install 2@ line drivers near each serial
- port so as to convert unbalanced to balanced (and conversely) and then
- use twisted pair cabling. But line drivers are expensive.
-
- Another way to increase the distance is to try to cancel out much of
- the magnetic field created by the currents in the transmit and receive
- data wires: TxD and RxD. To do this, ground return lines, which have
- current which is roughly equal (but in the opposite direction) are
- placed next to the the transmit and received wires. Twisted pair has
- the best cancellation. Some DEC terminals have two signal ground
- wires for this purpose. For example, one pair would be TxD and
- SG(TxD) where SG is signal ground. If you use ribbon cable, insure
- that the TxD and SG(TxD) wires are right next to each other.
- Similarly for the RxD.
-
- If there is only one signal ground wire provided by both the PC and
- the terminal, it may be split into two wires in a twisted pair cable
- for this purpose. You might think that return currents will be
- equally split between the two signal ground wires. This would cancel
- out only about half of the magnetic field. But it's better
- cancellation than this because return current prefers the path of
- least impedance. The return path of a data signal (such as TxD) has
- the lowest impedance (due to lower inductance) if it flows back in the
- same twisted pair. Although I've haven't seen any experimental test
- results for this method, it should allow longer cable lengths.
-
-
- 11.3.5. Hardware Flow Control cables
-
- If you expect to use hardware flow control (handshaking) you will
- likely need to make up your own cable (or order one made). Of course,
- if the connecters on the ends of a used cable remove, you might rewire
- it. See ``Installing DB Connectors''. You will need to determine
- whether or not the terminal uses the DTR pin for this, and if not,
- what pin (or pins) it uses. The set-up menus may give you a clue on
- this since there may be an option for enabling "DTR handshaking" (or
- flow control) which of course implies that it uses the DTR pin. It
- may also use the DSR pin. See ``Hardware Flow Control'' for a
- detailed explanation of it. Older terminals may have no provision for
- hardware flow control.
-
-
- 11.3.6. Cable tips
-
- The normal "straight thru" cable will not work unless you are using it
- as an extension cable in conjunction with either a null modem
- (crossover) cable or a null modem adapter. Make sure that the
- connectors on the cable ends will mate with the connectors on the
- hardware. One may use telephone cable which is at least 4-conductor
- (and possibly twisted pair). Shielded, special low-capacitance cable
- computer cable is best.
-
-
- 11.3.7. A kludge using twisted-pair cable
-
- See also ``Overcoming Length Limitations''. Although none of the
- EIA-232 signals are balanced for twisted pair one may attempt to use
- twisted-pair cable with it. Use one pair for transmit and another for
- receive. To do this connect signal ground to one wire in each of
- these 2 pair. Only part of the signal ground current flows in the
- desired wire but it may help. Due to the lower inductance of the
- twisted pair circuit (as compared to ground return current by some
- other path) more return (ground) current will confine itself to the
- desired twisted pair than one would expect from only resistance
- calculations. This is especially true at higher frequencies since
- inductive impedance increases with frequency. The rectangular wave of
- the serial port contains high frequency harmonics.
-
-
- 11.3.8. Cable grounding
-
- Pin 1 (of a DB25) should be chassis ground (also earth ground) but on
- cheap serial ports it may not even be connected to anything. A 9-pin
- connector doesn't even have a chassis ground. The signal ground is
- pin 7 and is usually grounded to chassis ground. This means that part
- of the signal current will flow thru the ground wires of the building
- wiring (undesirable). Cable shields are supposed to be only grounded
- at one end of the cable, but it may be better to ground both ends
- since it's better to have current in the shield than in the building
- wiring ??
-
-
- 11.4. Modem Connection
-
- By using a terminal-modem combination (without a computer) one may
- dial out to other computers. Up to the mid 1990s in the US, there
- were many "bulletin boards" one could dial out to. Some even provided
- connections to the Internet. But bulletin boards lost out in favor of
- the Internet.
-
-
- 11.4.1. Dialing out from a terminal
-
- Instead of connecting a terminal (or computer emulating a terminal)
- directly to a host computer using a cable it may be connected to the
- host via a telephone line (or dedicated private line) with a modem at
- each end of the line. The terminal (or computer) will usually dial
- out on a phone line to a host computer.
-
- Most people use a PC and modem for dialing out. The PC could have a
- terminal connected to a serial port and the person at the terminal may
- dial out using the PC. Connecting a real terminal directly to an
- external modem is more difficult since the real terminal isn't very
- intelligent and doesn't give as much feedback to the user. For
- dialing out, many terminals can store one or more telephone numbers as
- messages which may be "set-up" into them and are sent out to the modem
- by pressing certain function keys. Many modems can also store phone
- numbers. The modem initiation sequence must precede the telephone
- number. When the outgoing call is answered by another modem at the
- other end of the phone line, the the host computer on this modem may
- run a getty program to enable you to log in.
-
-
- 11.4.2. Terminal gets dialed into
-
- It's common for a computer running Linux to get dialed into. The
- caller gets a login prompt and logs in. At first glance, it may seem
- strange how a dumb terminal (not connected to any computer) could
- accept an incoming call, but it can. One possible reason for doing
- this is to save on phone bills where rates are not symmetric. Your
- terminal needs to be set up for dial-in: Set the modem at your
- terminal for automatic answer (Register S0 set to 2 will answer on the
- 2nd ring). You turn on the terminal and modem before you expect a
- call and when the call comes in you get a login prompt and log in.
-
- The host computer that dials out to your terminal needs to do
- something quite unusual. As soon as your modem answers, it needs to
- run login (getty). A host may do this by running the Linux program
- "callback" sometimes named "cb". Callback is for having computer A
- call computer B, and then B hangs up and calls A back. This is what
- you want if you are using computer A to emulate a terminal. For the
- case of a real terminal this may be too complex a task so the host may
- utilize only the "back" part of the callback program. The setup file
- for callback must be properly configured at the host. Callback makes
- the call to the terminal and then has mgetty run a login on that port.
- Mgetty by itself (as of early 1998) is only for dial-in calls but
- there is work being done to incorporate callback features into it and
- thus make it able to dial-out. As of early 1999 it didn't seem to
- have been done.
-
-
- 11.5. Telnet
-
- Telnet is a program which lets a text terminal (or a PC console)
- connect to a host computer over a network. No serial ports are used
- for the telnet connection. Of course if you are sitting at a real
- text terminal there is a serial connection to your own host. But when
- you run telnet, your host connects to another host via serial-less
- telnet.
-
- Telnet uses tcp/ip packets over various networks: the Internet, LANs,
- etc. You run telnet (as a client) and it connects to a telnet server
- on another computer on a network. Then you get a login prompt and log
- in just as if you were directly connected via a cable to a serial
- port.
-
-
- 11.6. Terminal Server Connection
-
- 11.6.1. What is a terminal server ?
-
- A terminal server is something that serves to connect a bunch of
- terminals to a host computer(s) via a network. Today this server is
- often located nearby or inside the host computer. If you directly
- connect some terminals to a PC or connect them via dial-up modems thru
- serial ports at each end, you don't need a terminal server.
-
- But if the terminals are connected to the host over a network, then
- you may need a terminal server to make the serial-to-network
- conversions. This is useful for devices such as printers and
- terminals that have no built-in network support. However the
- definition of "terminal server" has broadened to the case where all
- data flows entirely over a network (except of course within the
- computer itself) and where no serial ports are involved. The term
- "terminal" may include a thin client type terminal with a GUI. The
- network usually uses tcp/ip and/or ppp but other protocols (including
- protocol conversion) are sometimes supported.
-
- One way to connect a "terminal" (your PC console) to a network is to
- run telnet on your PC (assuming your PC has a network connection). At
- one time, terminal servers were dedicated hardware which could be used
- only as terminal servers. Today a PC can simultaneously serve as a
- terminal server thereby serving many terminals.
-
- Today, most terminal servers serve thin client terminals rather than
- text-terminals. The "Linux Terminal Server Project" is an example.
- But it can also serve text terminals using telnet. Such a text-
- terminal is likely to be just a PC monitor emulating a terminal of
- type "Linux". The terminal server is just software running on the
- host computer. Telnet server software is like a simple terminal
- server.
-
- A host that only has directly connected terminals (or modem
- connections without tcp/ip or ppp) is sometimes called a "terminal
- server". Although it's doing the same job as a real terminal server,
- it strictly speaking is not a terminal server.
-
-
- 11.6.2. Evolution of the "terminal server"
-
- Originally a terminal server served real text-terminals via the serial
- port. A server for real text-terminals would have a number of serial
- ports. The user would log in to the server and then get connected via
- tcp/ip, etc. to a host computer where s/he would login a second time
- again. Sometimes the first login would be automatic, or perhaps there
- would be a choice given the user as to what host computer (or printer)
- to connect to (or what protocol to use).
-
- The use of real text-terminals declined as the PC replaced mainframes.
- But the PC could emulate a terminal (using say minicom (Linux) or
- (hyper)terminal for MS). One could could then dial-out via a modem
- to a bulletin-board or the like. There would be a bank of modems to
- accept such calls and each modem would be connected to a serial port.
- The serial port could either be on a multiport card or on a dedicated
- terminal server. Note that in both the above cases there is no client
- software. It's not a client-server model.
-
- When the Internet became popular, one would run the PPP protocol on
- the phone line and still go thru a modem and "terminal server" at the
- ISP. This server would handle PPP and ultimately connect one to the
- Internet. But the PC was no longer emulating a text terminal since
- browser images were being displayed. Today with ISPs getting only
- digital signals from the phone company, they don't need real modems
- anymore. So what was a "terminal server" evolved into a "remote
- access server". It's infrequently been called a "digital terminal
- server". Note that 56k modem service requires that an ISP have a
- digital connection to the phone company.
-
- With remote access servers, instead of many individual telephone line
- cables connected to a terminal server, one now finds just a few cables
- with many digitized telephone calls on each cable (multiplexed). The
- multitude of connectors needed for large numbers of terminals or
- modems is no longer present on a remote access server and thus the
- successor to this type of terminal server can't readily serve text-
- terminals anymore.
-
- More recently with the advent of thin clients terminals, the term
- "terminal server" was revived to apply to the hosts that served the
- thin clients. Both MS Windows and Linux can serve thin clients.
-
- 11.7. Connector and Adapter Types
-
- A connector is more-or-less permanently attached to the end of a cable
- or to a hardware unit. There are two basic types of connectors used
- in serial communications: 1. DBxx with pins (such as DB25) and 2.
- modular telephone-style connectors.
-
- An adapter looks about like a connector but it has two ends. It is
- just like a cable that is so short that there is no cable part left at
- all --just different connectors on each end is all that remains. The
- adapter just plugs in on each side. It allows two incompatible
- connectors to mate with each other by going in between them.
- Sometimes the purpose of the adapter is to interchange wires.
- Obviously, one may use a special cable (perhaps homemade) as a
- substitute for an adapter.
-
-
- 11.7.1. Sex of connector/adapters
-
- Connectors (or one side of adapters) are either male or female. The
- connectors that have pins are male and the ones that have sockets
- (sometimes also called pins) are female. For modular connectors, the
- ones with exposed contacts are plugs while the ones with internal
- contacts (not easy to see) are jacks. Plugs are male; jacks are
- female.
-
-
- 11.7.2. Types of adapters
-
- There are three basic types of adapters: null modem, gender changers
- and port adapters. Some adapters perform more than one of these three
- functions.
-
- · null modem adapter: Reroutes wires. Like a null modem cable.
-
- · gender changer: Changes the sex of a cable end. Two connectors of
- the same sex can now connect (mate) with each other.
-
- · port adapter: Goes from one type of connector to another (DB9 to DB
- 25, etc.)
-
-
- 11.7.3. DB connectors
-
- (For how to install a DB connector on the ends of a cable see
- ``Installing DB Connectors''.) These come in 9 or 25 pins. The
- EIA-232 specs. call for 25 pins but since most of these pins are not
- used on ordinary serial ports, 9 pins is sufficient. See ``DB9-DB25''
- for the pin-out. The pins are usually numbered if you look closely
- enough or use a magnifying glass.
-
-
- 11.7.4. RJ modular connectors
-
- RJ means Registered Jack. These look like modern telephone connectors
- but are sometimes not compatible with telephone connectors. See also
- ``Installing RJ Connectors''. For use with serial ports they may be 6
- or 8 conductor. A few are 10-conductor but may not officially belong
- to the RJ series.
-
-
- 11.7.4.1. 6-conductors: RJ11/14, RJ12, and MMJ
-
- RJ11 are all the same size but may have 2, 4, or 6 conductors. If it
- has two conductors, it should be called a RJ11. If it has 4
- conductors, some call it a RJ14. If it has 6 conductors, many call it
- a RJ12 (but a RJ12 per the phone company has only 4 conductors).
- Seems confusing but they are all the same size and differ mainly by
- the number of conductor contacts present.
-
- A look-alike (almost) is a MMJ connector (6-conductor) used on later
- model VT (and other) terminals. It's sometimes referred to as a
- DEC-423 or a DEC RJ11. MMJ has an offset tab and is not compatible
- with RJ ones (unless the tab is cut off). However, some connectors
- have been made that are compatible with both MMJ and the RJ ones.
- Since MMJ connectors are both hard to find and may be expensive some
- people have forced a RJ (6 conductor) to fit MMJ by filing off the
- offset tab with a file.
-
- The MMJ (DEC) pinout is: 1-DTR, 2-TxD, 3-TxD_Gnd, 4-RxD_Gnd, 5-RxD,
- 6-DSR. Cyclades Cyclom-8Ys RJ12 has: 1-DTR, 2-TxD, 3-Gnd, 4-CTS,
- 5-RxD, 6-DCD. Specialix IO8+ has: 1-DCD, 2-RxD, 3-DTR/RTS, 4-Gnd,
- 5-TxD, 6-CTS. The pins of the RJ (and MMJ) are numbered similar to
- the RJ45.
-
-
-
- Plug Jack (or socket)
- (Looking at the end (Looking at the cavity
- end of a cable) in a wall or PC back)
- .________. .________.
- | 654321 | | 123456 |
- |__. .__| |__. .__|
- |__| |__|
-
-
-
- A standard MMJ null-modem cable has a MMJ connector at each end. It
- connects to the PC using a MMJ-to-DB adapter. This adapter plugs into
- a DB (say 25 pin) connector on the back of the PC and the MMJ
- connecter plugs into it. If you don't have such an adapter, you can
- make a custom cable with a MMJ (or filed RJ) connector on one end and
- a DB connector on the other end.
-
- The standard null-modem cable with two MMJ (or RJ11/14) connectors
- will connect: 1-6, 2-5, and 3-4. Note that such a cable supports
- DTR/DSR flow control which is not supported (yet) by Linux. Making up
- your own standard 6-conductor null-modem cable is very simple if you
- understand that the ordinary 4-conductor telephone cable from the wall
- to your telephone, used in hundreds of millions of homes, is also a
- null-modem cable. Find one and wire your cable the same way.
-
- If you lay such a cable (or your terminal null-modem cable) flat on
- the floor (with no twists) you will note that both plugs on the ends
- have their gold contacts facing up (or both facing down). Although
- it's symmetrical, it is also null- modem if you think about it a bit.
- One may put a few such cables together with inline couplers and
- everything works OK because each inline coupler is also a null-modem
- adapter. Two null-modem devices in series result in a straight-thru
- connection.
-
- Here's a custom cable diagram (by Mark Gleaves) for connecting MMJ to
- a 9-pin serial port using RTS/CTS flow control:
-
-
-
- DEC MMJ Linux PC DB9
- Pin Signal Signal Pin
- === ====== ====== ===
- 1 DTR -----------------------|---> DSR 6
- |---> CTS 8
- 2 TxD ---------------------------> RxD 2
- 3 SG (TxD)--------------------|--- SG 5
- 4 SG (RxD)--------------------|
- 5 RxD <--------------------------- TxD 3
- 6 DSR <-----------------------|--- RTS 7
- |--> DTR 4
- |--> CD 1
- (no connection) RI 9
-
-
-
- 11.7.4.2. 8-conductors and 10-conductors
-
- RJ45 and RJ48 are 8-conductor modular telephone plugs. There exists
- some 10-conductor connectors which are allegedly wider and will not
- mate with the 8-conductor ones. People have called the 10-conductor
- ones RJ45 and/or RJ48 but this may be incorrect. These connectors are
- used for both flat telephone cable and round twisted pair cable. The
- cable end of the connector may be different for round and flat cable.
- RJ48 has an extra tab so that a RJ48 plug will not push into a RJ45
- jack (but a RJ45 plug will mate with a RJ48 jack). They're used on
- some multiport serial cards and networks. Heres the pin numbers for
- an 8-conductor:
-
-
-
- Plug Jack (or socket)
- (Looking at the end (Looking at the cavity
- end of a cable) in a wall)
- .__________. .__________.
- | 87654321 | | 12345678 |
- |__. .__| |__. .__|
- |____| |____|
-
-
-
- 11.8. Making or Modifying a Cable
-
- 11.8.1. Buy or make ?
-
- You may try to buy a short, null modem cable. Just a "modem cable"
- will not work. Null modem cables are often labeled as serial printer
- cables (but serial printers are not very popular today and neither are
- the cables). Unfortunately, they will probably not work for hardware
- flow control (until Linux supports DTR flow control, possibly in
- 2001). Make sure the connectors on the cable ends will fit the
- connectors on your computer and terminal.
-
- But if you need longer cables to connect up terminals or need hardware
- flow control, how do you get the right cables? The right ready-made
- cables may be difficult to find (you might find them by searching the
- Internet), especially if you want to use a minimum (say 4) of
- conductors. One option is to get them custom made, which is likely to
- be fairly expensive although you might find someone to make them at
- prices not too much higher than ready-made cable (I did).
-
- A low-cost alternative is to buy used cables (if you can find them).
- If you get a used terminal, ask if they have a cable for it. Another
- alternative is to make your own. Even if you get used cables, they
- may need some changes to the pin wiring. In either case, this may
- require special tools. Most connectors that come with short cables
- are permanently molded to the cable and can't be rewired but most
- custom-made and homemade cables have connectors that can be rewired.
- One advantage of making your own cable is that the skills you learn
- will come in handy if a cable breaks (or goes bad) or if you need to
- make up another cable in a hurry.
-
-
- 11.8.2. Pin numbers of 9 and 25 pin connectors
-
- The pin numbers are often engraved in the plastic of the connector but
- you may need a magnifying glass to read them. Note DCD is sometimes
- labeled CD. The numbering of the pins on a female connector is read
- from right to left, starting with 1 in the upper right corner (instead
- of 1 in the upper left corner for the male connector as shown below).
- --> direction is out of PC.
-
-
-
- ___________ ________________________________________
- \1 2 3 4 5/ Looking at pins \1 2 3 4 5 6 7 8 9 10 11 12 13/
- \6 7 8 9/ on male connector \14 15 16 17 18 19 20 21 22 23 24 25/
- ------ -----------------------------------
-
-
-
- 11.8.3. Installing DB connectors on cable ends
-
- See ``DB Connectors'' for a brief description of them. Unfortunately,
- most cables one purchases today have molded connectors on each end and
- can't be modified. Others have connectors which unscrew and can be
- rewired. If you are making up cable or modifying an existing one then
- you need to know about pins. There are two types: soldered and
- crimped.
-
- The crimped pins require a special crimping tool and also need an
- "insertion/extraction" tool. But once you have these tools, making up
- and modifying cable may be faster than soldering. If you are
- connecting two wires to one pin (also needed if you want to jumper one
- connected pin to another pin) then soldering is faster (for these
- pins). This is because the crimped pins can only take one wire each
- while the soldered ones can accept more than one wire per pin.
-
- To insert crimped pins just push them in by hand or with the insertion
- tool. Using the tool for either insertion of removal first requires
- putting the tool tip around the wire. The tool tip should completely
- encircle the wire at the the back of the pin.
-
- Removing a pin with this tool is a little tricky. These directions
- can be best understood if you have both the tool and wires in front of
- you as you read this. With the tool tip around the wire insert the
- tool as far as it will go into the hole (about 1 1/2 cm. Some tools
- have a mark (such as a tiny hole) on them to indicate how far to
- insert it. The tool tip should have a tapered gap so that you may get
- the tip around the wire by starting it in where the gap is wider than
- the wire. The tool may have 2 tips. The one that is the most
- difficult to get around the wire is also the one that removes the wire
- the easiest since it almost completely envelops the wire.
-
- With the tip properly inserted pull on both the tool and the wire with
- a gentle pull. If it doesn't come out, the tool was likely not
- inserted correctly so either push it in more or twist it to a
- different position (or both). Perhaps you should have used another
- tip that fits tighter around the pin. Using this tool, one may
- readily convert a straight-thru cable to a null-modem cable, etc.
-
- There can be problems using the "insertion/extraction" tool. If the
- tools will not insert on the back of the pin, it could be that the pin
- was not neatly crimped to the wire and is sort of square where it
- should be round, etc. If a pin starts to come out but will not pull
- out all the way, the pin may be bent. Look at it under a magnifying
- glass. Straightening a pin with needle-nose pliers may damage the
- gold plating but you may have to straighten it to remove it.
- Sometimes a stuck pin may be pushed out with a thick screwdriver blade
- tip (or the like) but if you push too hard you may gouge the plastic
- hole or bend the pin:.
-
- Don't try soldering unless you know what you're doing or have read
- about how to do it.
-
-
- 11.8.4. Installing RJ connectors
-
- These are telephone modular connecters one type of which is used for
- most ordinary telephones. But there are many different types (see
- ``RJ Modular Connectors'').
-
- These are not easy to reuse. You might be able to pull the wires out,
- push in something wedged that would lift up the gold-colored contacts
- and reuse the connector. There are special crimping tools used to
- install them; a different tool for each type.
-
- If you don't have a crimping tool, installation is still possible (but
- difficult) using a small screwdriver (and possibly a hammer). Push in
- the cable wires and then push each gold-colored contact down hard with
- a small screwdriver that will just fit between the insulating ridges
- between the contacts. You may damage it if you fail to use a
- screwdriver with a head almost the same thickness as the contacts or
- if the screwdriver slips off the contact as you are pushing it down.
- You may also use a small hammer to pound on the screwdriver (push
- first by hand).
-
- Be sure to not hurt the "remove lever" on the connecter when you push
- in the contacts. Don't just set it down on a table and push in the
- contacts. Instead, put a shim (about 1 mm thick) that fits snugly in
- the crevice between the lever and the body. For such a shim you may
- use thick cardboard, several calling cards, or wood. Since the bottom
- of the connector (that you will put on the table) isn't level (due to
- the "remove lever), make sure that the table top has something a
- little soft on it (like a sheet of cardboard) to help support the non-
- level connector. Even better would be to put another 1mm shim under
- the first 6mm of the connector, supporting it just under where you see
- the contacts. A soft tabletop wouldn't hurt either. Another method
- (I've never done this) is to hold the connector in a vice but be
- careful not to break the connector.
-
- As compared to using a crimping tool, installing it per above takes a
- lot longer and is much more prone to errors and failure but it's
- sometimes more expedient and a lot cheaper than buying a special tool
- if you only have one or two connectors to install.
-
-
- 12. Set-Up (Configure) in General
-
- 12.1. Intro to Set-Up
-
- Configuring (Set-Up) involves both storing a configuration in the non-
- volatile memory of the terminal, and putting commands in start-up
- files (on your hard disk) that will run each time the computer is
- powered on (or possibly only when the run-level changes). This
- section gives an overview of configuring and covers the configuring of
- the essential communication options for both the terminal and the
- computer. The next two major sections cover in detail the
- configuration of the terminal (see ``Terminal Set-Up'' and the
- computer (see ``Computer Set-Up (Configure) Details''.
-
-
- 12.2. Terminal Set-Up (Configure) Overview
-
- When a terminal is installed it's necessary to configure the physical
- terminal by saving (in its non-volatile memory which is not lost when
- the terminal is powered off) the characteristics it will have when it
- is powered on. You might be lucky and have a terminal that has
- already been set-up correctly for your installation so that little or
- no terminal configuration is required.
-
- There are two basic ways of configuring a terminal. One is to sit at
- the terminal and go thru a series of set-up menus. Another is to send
- escape sequences to it from the host computer. Before you can send
- anything to the terminal (such as the above escape sequences), its
- ``Communication Interface'' options such as the baud rate must be set
- up to match those of the computer. This can only be done by sitting
- at the terminal since the communications must be set up right before
- the computer and the terminal can "talk" to each other. See
- ``Terminal Set-Up''.
-
-
- 12.3. Computer Set-Up (Configure) Overview
-
- Besides possibly sending escape sequences from the computer to
- configure the terminal, there is the configuring of the computer
- itself to handle the terminal. If you're lucky, all you need to do is
- to put a "getty" command in the /etc/inittab file so that a "login:"
- prompt will be sent to the terminal when the computer starts up. See
- the section ``Getty (used in /etc/inittab)'' for details.
-
- The computer communicates with the terminal using the serial device
- driver software (part of the kernel). The serial device driver has a
- default configuration and is also partly (sometimes fully) configured
- by the getty program before running "login" at each terminal.
- However, additional configuration is sometimes needed using programs
- named "stty" and "setserial". These programs (if needed) must be run
- each time the computer starts up since this configuration is lost each
- time the computer powers down. See ``Computer Set-Up (Configure)
- Details''.
-
-
- 12.4. Many Options
-
- There are a great many configuration options for you to choose from.
- The communication options must be set right or the terminal will not
- work at all. Other options may be set wrong, but will cause no
- problem since the features they set may not be used. For example, if
- you don't have a printer connected to the terminal it makes no
- difference how the printer configuration parameters are set inside the
- terminal. This last statement is not 100% correct. Suppose that you
- have no printer but the computer (by mistake) sends the terminal a
- command to redirect all characters (data) from the computer to the
- printer only. Then nothing will display on the screen and your
- terminal will be dead. Some terminals have a configuration option to
- inform the terminal that no printer is attached. In this case the
- terminal will ignore any command to redirect output to the "printer"
- and the above problem will never happen. However, this doesn't help
- much since there are many other erroneous commands that can be sent to
- your terminal that will really foul things up. This is likely to
- happen if you send the terminal a binary file by accident.
-
- In some cases a wrong setting will not cause any problem until you
- happen to run a rare application program that expects the terminal to
- be set a certain way. Other options govern only the appearance of the
- display and the terminal will work fine if they are set wrong but may
- not be as pleasant to look at.
-
- Some options concern only the terminal and do not need to be set at
- the computer. For example: Do you want black letters on a light
- background? This is easier on the eyes than a black background.
- Should a key repeat when held down? Should the screen wrap when a
- line runs off the right end of the screen? Should keys click?
-
-
- 12.5. Communication Interface Options
-
- Some of these communication settings (options) are for both the
- terminal and the computer and they must be set exactly the same for
- both: speed, parity, bits/character, and flow control. Other
- communication options are only set at the terminal (and only a couple
- of these are essential to establish communications). Still others
- such as the address and interrupt (IRQ) of the physical port ttyS2 are
- set only at the computer using the "setserial" command. Until all of
- the above essential options are compatibly set up there can be no
- satisfactory serial communication (and likely no communication at all)
- between the terminal and the computer. For the terminal, one must set
- these options manually by menus at each terminal (or by using some
- sort of special cartridge at each terminal). The host computer is
- configured by running commands each time the computer is powered up
- (or when people log in). Sometimes the getty program (found in the
- /etc/inittab file) which starts the login process will take care of
- this for the computer. See ``Getty (used in /etc/inittab)''
-
- The settings for both the computer and the terminal are:
-
- · ``Speed (bits/second) ''
-
- · ``Parity''
-
- · ``Bits per Character ''
-
- · ``Flow Control ''
-
- Some essential settings for the terminal alone are:
-
- · ``Port Select''
-
- · Set communication to full duplex (=FDX on Wyse terminals)
-
- If the ``Getty (used in /etc/inittab)'' program can't set up the
- computer side the way you want, then you may need to use one (or both)
- of the ``Stty & Setserial'' commands.
-
-
- 12.5.1. Speed
-
- These must be set the same on both the terminal and the computer. The
- speed is the bits/sec (bps or baud rate). Use the highest speed that
- works without errors. Enabling flow control may make higher speeds
- possible. There may be two speeds to set at the terminal: Transmit
- and Receive, sometimes abbreviated T and R. Usually they are both set
- the same since stty in Linux doesn't seem to have the option yet of
- setting them differently. (There is an option to do this with the
- "stty" command but it seems to actually set them both the same.)
- Common speeds are 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, ...
- The slower speeds (like 600) are for printers and hard-copy terminals.
-
-
- 12.5.2. Parity & should you use it ?
-
- For a definition see ``Parity Explained''. Parity-disabled is often
- the default. To enable parity, you must both enable it and then
- select either even or odd parity. It probably makes no difference if
- it's odd or even. For terminals there are sometimes settings for both
- transmit and receive parity. You should set both of these the same
- since stty at the computer doesn't permit setting them differently.
- The PC serial port usually can't support different parities either.
- Some terminal are unable to set receive parity and will simply always
- ignore received parity bits. On some older terminals if you use
- 8-data-bits per byte then parity will not work since there is no room
- in the hardware for the extra parity bit.
-
- Should you use parity at all? Parity, while not really necessary, is
- nice to have. If you don't have parity, then you may get an incorrect
- letter here and there and wind up trying to correct spelling errors
- that don't really exist. However parity comes at a cost. First, it's
- more complicated to set up since the default is usually no parity.
- Secondly, parity will slow down the speed with which bytes travel over
- the serial cable since there will be one more bit per byte. This may
- or may not slow down the effective speed.
-
- For example, a hard-copy terminal is usually limited by the mechanics
- of the printing process. Increasing the bytes/sec when the computer
- (its UART chip) is transmitting only results in more flow-control
- "halt" signals to allow the mechanical printing to catch up. Due to
- more flow-control waits the effective speed is no better without
- parity than with it. The situation is similar for some terminals:
- After you implement parity there may be fewer flow-control waits per
- unit time resulting in more bits/sec (average). However, due to the
- added parity bits the bytes/sec (average) stays the same.
-
- One option is to install terminals with no parity. Then if parity
- errors are noticed, it can be implemented later. To spot possible
- errors with no parity, look for any spelling errors you don't think
- you made. If you spot such an error, refresh the screen (retransmit
- from the computer). If the error goes away, then it's likely a parity
- error. If too many such errors happen (such as more than one every
- few hundred screens) then corrective action is needed such as: Enable
- parity and/or reduce speed, and/or use a shorter/better cable.
- Enabling parity will not reduce the number of errors but it will tell
- you when an error has happened.
-
- Just the opposite policy is to initially enable parity. Then if no
- parity errors (error symbols on the CRT) are ever seen (over a
- reasonable period of time, say a month or two) it may be safely
- disabled.
-
-
- 12.5.3. Bits/Character
-
- This is the character size (the number of data bits per character
- excluding any parity bit). To use international character sets you
- need 8 bits. But it's not of much use unless your terminal has the
- fonts for them. See ``Character-Sets'' If you are only going to use
- ASCII characters, then select 7-bits since it's faster to transmit 7
- bits than 8. Some very old terminals only support 7-bit characters.
-
-
-
- 12.5.4. Which Flow Control (Handshaking) ?
-
- The choice is between "hardware" (for example dtr/cts) or "software"
- (Xon/Xoff) flow control. While hardware flow control may be faster
- (if the one or two extra wires for it are available in the cable and
- if the terminal supports it) in most cases Xon/Xoff should work OK.
- Some people report that they solved disturbing problems (see below) by
- converting to hardware flow control but software flow control has
- worked fine at other installations (and for me personally).
-
- If you use software (Xon/Xoff) flow control and have users who don't
- know about it, then they may accidentally send an Xoff to the host and
- lock up their terminal. While it's locked, they may type frantically
- in a vain attempt to unlock it. Then when Xon is finally sent to
- restore communication, all that was typed in haste gets executed,
- perhaps with unexpected results. They can't do this with hardware
- flow control. See ``Flow Control'' for an explanation of flow
- control.
-
-
- 12.5.5. Port select
-
- Since most terminals have two or more connectors on the back, it is
- usually possible to assign one of these connecters to connect to the
- host computer and assign another connector to be the printer port.
- The connector may have a name next to it (inspect it) and this name
- (such as Aux, Serial 2, or Modem) may be assigned to either be the
- main host connection or the printer connection (or the like).
-
-
- 12.6. Quick Attempt
-
- While all the above may seem overly complex, to get a terminal working
- is often fairly simple. The ``Quick Install'' section describes a
- simple way to try to do this. But if that doesn't work or if you want
- to make the display look better and perform better, more reading will
- be needed.
-
-
- 13. Terminal Set-Up (Configure) Details
-
- Except for the next subsection on sending escape sequences to the
- terminal, this section mainly presents the details of setting up the
- terminal manually by sitting at the terminal and going thru menus. If
- you haven't already done so, you should read ``Terminal Set-Up
- (Configure) Overview''. It's best if you have a terminal manual, but
- even it you don't there is information here on many of the options
- which you might possibly need to set.
-
- The communication parameters such as its baud rate must always be set
- up at the terminal since if this is not done there can be no
- communication with the terminal. Once communication is established
- you have two choices for doing the rest of the terminal configuration.
- You may continue to configure manually at the terminal and save the
- results in the terminal's non-volatile memory or you may do this by
- sending escape sequences to the terminal from the computer each time
- the terminal is powered on (or the like).
-
- If you know how to set up and save a good configuration inside the
- terminal it may be the best way. If you don't, you might want to just
- send the init string from terminfo to your terminal each time you use
- the terminal. Perhaps doing nothing will still give you a usable
- terminal. You (or an application program) can always change things by
- sending certain escape sequences to the terminal.
-
-
- 13.1. Send Escape Sequences to the Terminal
-
- Once the communication interface is established, the rest of the
- configuration of the terminals may sometimes be done by sending escape
- sequences to the terminals from the computer. If you have a large
- number of terminals, it may be worthwhile to write (or locate) a shell
- script to automatically do this. There may (or may not) be a command
- you can send to a terminal to tell it to save its current set-up in
- its non-volatile memory so that it will be present the next time the
- terminal is powered on.
-
- There is an simple way to send these escape sequences and a complex
- way. Using the simple way, you never look up escape sequences but
- issue commands that automatically find an appropriate escape sequence
- in the terminfo database and send that. Unfortunately, not all the
- escape sequences which you might want to send are always in the
- terminfo database. Thus the more complex (but possibly better) way is
- to directly send escape sequences.
-
- For this complex method you'll need an advanced manual. Old terminal
- manuals once included a detailed list of escape sequences but newer
- ones usually don't. To find them you may need to purchase another
- manual called the "programmers manual" (or the like) which is not
- supplied with the terminal. A ``Esc Sequence List'' for some
- terminals is on the Internet but it's terse and likely incomplete.
-
- Even without a manual or the like, you may still send commands to
- configure the terminal by using the programs "tput" and "setterm".
- See ``Changing the Terminal Settings''. You could just send the
- terminal an init string from the terminfo entry if the init string
- sets up the terminal the way want it. See ``Init String''. Unless
- you plan to have these sequences sent from the computer to the
- terminal each time the terminal is powered on, you must somehow save
- the settings in the non-volatile memory of the terminal.
-
-
- 13.2. Older Terminals Set-Up
-
- On older terminals look at the keyboard for labels just above the top
- row of numeric keys. If they exist, these labels may be what these
- keys do in set-up mode. Some older terminals may have only one "set-
- up" menu. Still older ones have physical switches. In some cases not
- all the switches are well labeled but they may be well concealed. Of
- course, if you set something with a switch, it's "saved" and there is
- no need to save the setting in non-volatile memory.
-
-
- 13.3. Getting Into Set-Up (Configuration) Mode
-
- To select options (configure) at the terminal, you must first enter
- "set-up" mode and then select options (i.e. configure) using menus
- stored inside the terminal and displayed on the screen. To do this,
- the terminal does not even need to be connected to a computer. How to
- get into set-up mode is covered in the terminal's manual, but here's
- some hints that may help:
-
- If there's a "set-up" key try pressing it. Also try it shifted.
-
- · Wyse: First try the shifted "Select" key; then substitute Ctrl for
- shifted in all of the above.
-
- · VT, Dorio: F3 may be the set-up key. On VT420 and later models
- this key may have been programmed to do something else so turn off
- the power. When you turn on the power again, hit the F3 key as
- soon as you get an initial screen message.
-
- · IBM: 3151: Ctrl-ScrollLock. 3153: Ctrl-Minus_on_Keypad (or like
- 3151)
-
- To move around in the set-up menus, try the arrow keys. Use Return,
- Space, or a special key ("toggle" on old terminals) to select. To
- exit set-up mode select exit from a menu (or on some older terminals
- press the set-up key again).
-
-
- 13.4. Communication Options
-
- For the terminal to work at all, speed, parity, :its/character, and
- communication mode must be set correctly. Incorrect flow control may
- cause loss and/or corruption of data seen on the screen. The essential
- communication options were dealt with (for both the terminal and
- computer) in another section: See ``Communication Interface''. The
- following list provides some links to that section, as well as some
- additional communication options set only at the terminal.
-
-
- · ``Speed (bits/second) '' (baud rate): 9600, 19200, etc.
-
- · ``Parity'' none, even, odd, mark, space
-
- · ``Bits per Character '' {Data}: 7 or 8
-
- · ``Flow Control:'' or Handshake {Hndshk}: none, Xon-Xoff, or
- hardware (DTR, etc).
-
- · Receiver Handshake {Rcv Hndshk} protects data being Received by the
- terminal by transmitting flow-control signals to the host.
-
- · Transmitter Handshake {Xmt Hndshk} is protection of data being
- Transmitted by the terminal. The terminal receives flow-control
- signals (and locks/unlocks the keyboard). Includes "Incoming
- Xon/Xoff".
-
- · number of stop bits: 1 or 2. See ``Voltage Sequence for a Byte''
-
- · Flow control level {Rcv Hndshk Level} {{Xoff at ...}}: Flow control
- will send "stop" when this number of bytes in the terminal's buffer
- is exceeded.
-
- · ``Communication Mode'' {Comm}: ``Full Duplex {FDX}, Half Duplex
- {HDX}'' {{Local Echo}}, ``Local Mode'' {{Online/Local}}
-
- · Transmit Rate (Speed) Limit {Xmt Lim}: limits the transmit rate to
- the specified cps (chars/sec) even though the baud rate setting may
- be at a higher speed.
-
- · Function-Key Rate Limit: as above but for function key messages.
-
- · ``Port Select'': Which physical connecter is for the host {Host
- Port} ?
-
-
- 13.5. Saving the Set-up
-
- Your set-up must be saved in the non-volatile memory of the terminal
- so that it will be effective the next time you turn on the terminal.
- If you fail to save it, then the new settings will be lost when you
- turn off the terminal. Before you go to the trouble of setting up a
- terminal, make sure that you know how to save the settings. For
- modern terminals the save command is done via a menu. In some older
- terminals, only the manual tells how to save. For many of these you
- press Ctrl-S to save.
- 13.6. Set-Up Options/Parameters
-
- What follows in this section describes some of the options which are
- available in the set-up menus of many terminals. Options are also
- called parameters or features. Many options may be called "modes".
- Setting options is often called "configuring". Many of these options
- may also be set by sending certain escape sequences to the terminal.
- Different models and brands of terminals have various options and the
- same option may be called by different names (not all of which are
- given here) Terse names used by Wyse are enclosed in {...}. Names
- used mostly for VT terminals are enclosed in {{...}}.
-
-
- 13.7. Emulation {Personality} {{Terminal Modes}}
-
- Most modern terminals can emulate several other terminals. The
- terminal can likely do more if it is set to emulate itself (actually
- no emulation) {native personality}. Sometimes there are 2 different
- emulations for the same model of terminal. For example VT220-7
- emulates a VT220 with 7-bits/byte while VT220-8 emulates a VT220 with
- 8-bits/byte (256 possible characters).
-
- Older models of terminals usually have fewer features than newer
- models. Suppose one wanted to emulate an old terminal but also wanted
- some of the advanced capabilities of the later model terminal they are
- sitting at. This is sometimes possible (to some degree). This
- feature is sometimes called {Enhance} (or Enhanced ??).
-
-
- 13.8. Display Options
-
- 13.8.1. Character Cell Size {Char Cell}
-
- This is the size of the cell in which a character fits. It is
- measured in pixels (=tiny dots). The more dots, the better the
- resolution. 10x16 is 10 dots wide by 16 dots high (16 rows and 10
- columns). Note the notation is inverted as compared to the notation
- for matrix dimensions which gives rows (height) first.. Also, the
- character cell includes rows and columns of pixels allocated for the
- space between adjacent characters so the cell size which defines the
- boundaries of an actual character may be smaller.
-
-
- 13.8.2. Columns/Lines
-
- Usually 80 columns and 24 or 25 lines. This means that there may be
- up to 80 characters in a row (line) on the screen. Many terminals
- have a 132 column option but unless you have a large screen, the tiny
- characters may be hard to read. {{Set 132 column mode}}. If you set
- 25 lines, make sure that this is in the terminfo. You should also put
- "export LINES=25" into /etc/profile and also use: "stty -F /dev/ttySx
- rows 25". If you don't it might result in a scrolling problem (see
- ``Terminal doesn't scroll''
-
-
- 13.8.3. Cursor
-
- The cursor may be set to appear as a rectangle (= block) {Blk}. Other
- options are underline {Line} or blinking. I prefer non-blinking
- {Steady} block since it's big enough to find quickly but there is no
- distractive blinking. If you set it invisible (an option on some
- terminals) it will disappear but new letters will appear on the screen
- as you type at the invisible cursor.
-
-
-
- 13.8.4. Display Attributes (Magic Cookies)
-
- ``Display Attributes'' may either be magic cookies or be attribute
- bytes assigned to each character. For magic cookies, there is a limit
- to their extent: Are they in effect to the end of the line or to the
- end of the page? It's best to use attribute bytes (which could
- actually be half-bytes = nibbles).
-
-
- 13.8.5. Display Control Characters {Monitor}
-
- May be called various names such as "Display Controls". When off
- (normal) it's "Interpret Controls". When set on, you see the escape
- sequences from the host (which you normally never see on the screen).
- So that these sequences may be viewed in sequence on a line, they are
- not acted upon (interpreted) by the terminal. Except that a CR LF
- sequence creates a new line. See ``Control Codes''.
-
-
- 13.8.6. Double Width/Height
-
- Some terminals can have their characters double width and/or double
- height. This feature is seldom needed. When changing a line to
- double width (DW) the right half (RH) is pushed off the screen and
- there is the question of whether or not to delete (erase) it.
- "Preserve" means to keep the RH of DW lines. When in double height
- mode, it may be necessary to send each such line twice (the 2nd time
- down one row) in order to get a double-height line on the screen.
-
-
- 13.8.7. Reverse Video {Display} (Background Light/Dark)
-
- Normal video is light (white, green, amber) letters (foreground) on a
- dark (black) background. Reverse video {Display Light} is the
- opposite: black text on a light background. This is easier on the
- eyes (unless the room is dark).
-
-
- 13.8.8. Status Line
-
- A status line is a line at the top or bottom of the screen that
- displays info about the application program you are running. It's
- often highlighted in some way. With a status line enabled, an
- application can send the terminal a special escape sequence which
- means that the text that follows is for the status line. However,
- many applications don't use this feature but instead only simulate a
- real status line by direct cursor positioning. The ordinary user
- looking at it doesn't know the difference.
-
-
- 13.8.9. Upon 80/132 Change: Clear or Preserve?
-
- When switching the number of columns from 80 to 132 (or conversely)
- should the data displayed in the old format be erased (cleared) or
- preserved? {80/132 Clr} {{Screen Width Change}}. It should make no
- difference how you set this option since if an application program
- uses 132 columns, it should set this option appropriately via a
- control sequence.
-
-
- 13.9. Page Related Options
-
- For a Wyse terminal to be able to access multiple pages of display
- memory {Multipage} must be set to on.
-
-
- 13.9.1. Page Size
-
- The terminal memory may be divided up into a number of pages. See
- ``Pages'' and ``Pages (definition)'' for explanations of pages. You
- may partition the page memory into a number of pages of selected
- length. Linux applications don't seem to use pages at present so it
- shouldn't make much difference how you set this up.
-
-
- 13.9.2. Coupling (of cursor & display)
-
- The terminal memory may be divided up into a number of pages. See
- ``Pages'' and ``Pages'' for explanations of pages. When the cursor is
- moved to a location in video memory not currently displayed (such as
- another page, or on the same page but to a location not displayed on
- the screen) should the display change to let one view the new cursor
- location? If so, this is called "Coupling". For cursor movement
- within the same page there is "Vertical Coupling" and "Horizontal
- Coupling". For movement to another page there is "Page Coupling".
-
-
- 13.10. Reporting and Answerback
-
- The terminal will identify itself and its state, or send out a pre-
- recorded message in response to certain escape sequences.
-
-
- 13.10.1. Answerback Message (String)
-
- You may write a short message during set-up which may optionally be
- sent to the host at power-up or be sent to the host in response to a
- request from the host (perhaps the ENQ (inquire) control character).
-
-
- 13.10.2. Auto Answerback
-
- If set, sends the answerback message to the host at power-on without
- the host asking for it. Do any "getty" processes look for this ??
-
-
- 13.10.3. Answerback Concealed
-
- If set, will never let anyone see the answerback message (except of
- course the host computer). If it needs to be changed, deselect
- "answerback concealed" and the formerly concealed message will be
- destroyed so you then may enter a new message (but you don't get to
- see the old one).
-
-
- 13.10.4. Terminal ID {ANSI ID}
-
- The terminal sends this reply in answer to a request for identity.
-
-
- 13.11. Keyboard Options
-
- 13.11.1. Keyclick
-
- When set, pressing any key makes a click (broadcast by a tiny
- loudspeaker in the keyboard). These clicks annoy some people and I
- think it's best to set keyclick off.
-
-
-
- 13.11.2. Caps Lock {Keylock}
-
- When the Caps-Lock key is down, should only the alphabetic keys
- generate shifted characters? If set to {Caps} or upper-case-only then
- hitting a number key with the Caps-Lock on will type the number. To
- get the symbol above the number one must manually hold down the shift
- key. This is the normal mode. If set to {Shift} then all keys type
- the shifted character when Caps-Lock is on (hitting the 5 key should
- type % without holding down Shift, etc.).
-
-
- 13.11.3. Auto Repeat {Repeat}
-
- If a key is held down then that key is repeatedly "typed". This is
- handy for repeatedly typing the same character to create a line across
- the page.
-
-
- 13.11.4. Margin Bell
-
- When the cursor is 8 columns away from the right side of the display,
- a bell is rung (like on an old typewriter). Almost all editors will
- automatically create a new line if needed (no need to hit the Return
- key) so this feature is seldom needed.
-
-
- 13.11.5. Remapping the Keys
-
- The code sent to the host when a key is pressed is normally the ASCII
- code for that key (depends also on Shift and Control key). On some
- terminals you may make any key send any code you wish. That is, you
- may completely remap the keyboard by setting up the terminal that way.
- This may be useful for some foreign languages and Dvorak keyboard
- layouts, etc. which permit one to type faster. Even for terminals
- that don't have the feature, there is software to remap the keyboard
- (and screen also). It's something like a device driver which uses a
- pseudo terminal. See ``Character Mapping: mapchan''
-
-
- 13.11.6. Corner Key (for Wyse only)
-
- Wyse terminals have a key near the lower left corner which may be set
- to do various things. Its may be labelled "Funct", "Compose
- Character", "Alt", "Hold" or "Scroll Lock". Early models don't have
- all of the following options:
-
-
- · Hold: No-Scroll. Hitting it stops the flow of data (using flow
- control) to the terminal. Hitting the key again restores normal
- flow.
-
- · Compose: Hitting it followed by certain other keys permits one to
- generate a limited number of pre-defined non-Latin characters.
-
- · Meta: Holding it down while typing another key sets the high-order
- bit on each byte. Are there models where it acts like a toggle to
- lock in the meta effect ??
-
- · Funct: Holding it down while typing any alphanumeric key gets a
- header (SOH) and trailer (CR) byte framing the ASCII byte code.
-
- · Kpd Compose: Holding it down while typing a decimal number on the
- numeric keys (followed by "enter") sends out the same number in
- hexadecimal ??
-
-
- 13.11.7. Numeric Keypad or Arrow Keys Sends
-
- The numeric keypad (the rectangle of mostly numeric keys to the right
- of the main part of the keyboard) can be set to send special codes
- which will do special things in certain application programs. Ditto
- for the arrow keys. There is thus a "normal" mode where they send
- what is shown on the keycap (or the normal code sequence for an arrow-
- key) and an "application" mode where special escape sequences are
- sent. In some cases there is a "hex" numeric mode which is almost
- like normal numeric mode except that 6 non-numeric keys send the
- letters A-F. Thus one may type for example "B36F" on the numeric
- keypad.
-
-
- 13.11.8. What does shifted-del and shifted-bs send?
-
- Depending on how they're set up, shifted-del sometimes sends the
- control character CAN and shifted backspace sometimes sends DEL.
-
-
- 13.11.9. PC Scan Codes
-
- Many terminals can emulate a PC keyboard by sending PC scancodes (see
- Keyboard-and-Console-HOWTO) instead of ASCII codes. This is mostly
- used with special Multiuser DOS OSs. It won't work with ordinary MS
- DOS. See ``Non-Linux OSs'' However, hardly any Linux programs that
- run via the serial port can accept scancodes. If this is the latest
- version of this HOWTO, let me know if any programs do this. I think
- Foxpro can do it. You need to define smsc and rmsc in the terminfo,
- and perhaps pctrm.
-
- When using scancodes it's best to use hardware flow control since
- normal software flow control conflicts with some of the codes (??).
- If you do use software flow control, you must use the XPC type of flow
- control. It uses 0x65 and 0x67 for on and off characters. It must be
- set this way both in the terminal and by stty for the PC.
-
-
- 13.11.10. Alternate Characters
-
- Some keys may have alternative letters on them. When keys is set to
- "Typewriter" they send what they would normally send on a typewriter.
- When keys is set to something else the alternative characters are
- sent.
-
-
- 13.12. Meaning of Received Control Codes
-
- 13.12.1. Auto New Line {Newline}
-
- In this case "New Line" means a new line starting at the left margin
- below the current line. In Linux and C "new line" (NL) may have a
- different meaning: the line-feed control character LF also called new-
- line or NL. This is because in Linux text files, the LF character
- means a "new line starts here" so it's labeled NL. Normally, a LF
- (NL) sent to a terminal only results in the cursor jumping down one
- line below where is was and does not move the cursor back to the start
- of this "new line".
-
- If Auto New Line is set, the above "normal" situation is canceled and
- a physical new line is created on the display upon receiving a LF from
- the host. This is exactly what one wants in Linux. Except that (when
- Auto New Line is set) the Return (or Enter) key sends a CR LF sequence
- to the host (for Wyse and VT100, but for VT420 ??). Since Linux uses
- LF as a "new line" marker in files, Linux would like only a LF to be
- sent (and not a CR LF). Thus the "New Line" option is seldom used.
- Instead, the required translations are made by the serial port device
- driver by default. It is as if one gave the command "stty onlcr
- icrnl". But you don't need to do this since it's the default.
-
-
- 13.12.2. Auto Line Feed {Rcv CR}
-
- This is just another type of "Auto New Line". When a CR (carriage
- return) character is received, a LF (line feed) action is added
- resulting in a new line being displayed. Since Linux marks the end of
- lines with LF, this option is not used.
-
-
- 13.12.3. Recognize Del (Wyse Only ??) or Null
-
- If off, the DEL character received by the terminal is ignored. If on
- the DEL performs a destructive backspace. Null characters are usually
- ignored in any case. Both DEL and NULL are sometimes used for
- padding. See ``Padding''
-
-
- 13.13. Where New Text Goes
-
- 13.13.1. Line Wrap
-
- Also called "Auto Wrap(around)". What happens when the right edge of
- the screen is reached (col. 80, etc) and no return character (or the
- like) has been sent from the host? If Line Wrap is set, then the rest
- of the line displays on the line below, etc. Otherwise, the rest of
- the line is lost and is not seen on the screen. Any good application
- should handle the situation correctly (provided the terminfo knows how
- Line Wrap is set). Thus even if Line Wrap is not set, the application
- should either wrap the screen for long lines or provide another way
- for you to view the cutoff tail of long lines (by use of the arrow
- keys, etc). But a raw copy command (and other situations) may not do
- this so it's often best to set line wrap.
-
- For an 80 col. screen, most terminals only wrap if the 81st character
- from the host is a graphic (printable) character. This allows for the
- case where 81st character from the host might be "return" or a
- "newline" (non-graphic characters) which means that the application is
- handing the wrapping OK and intervention by the terminal is not
- needed.
-
-
- 13.13.2. Scrolling
-
- Scrolling {Scrl} is where all the lines on the screen move up or down.
- Its also called "panning" which includes movement sideways. In
- ordinary scrolling lines roll off the bottom or top of the screen and
- disappear, and new lines from the host appear at the opposite edge
- (top or bottom). There are 3 types of this: smooth, jump, or burst.
- Burst is not really scrolling since its an instant replacement of an
- old screenfull by a new one (although some lines on the new screen may
- be from the old screen). Jump is where new lines jump into view one
- at a time. Smooth {Smth} is where the text moves at a steady speed
- upward or downward. If the smooth scroll rate is slow enough, one may
- read the newly visible lines when they are still scrolling (in
- motion).
-
- Smooth scrolling on slow terminals was once useful since one could
- continue reading as the display was scrolling. But with higher baud
- rates, jump scroll is so fast that little time is lost as the new
- display appears. Since it takes a little longer to read scrolling
- text than fixed text, it may actually waste more time if smooth
- scrolling is selected.
- If (auto)scrolling {Autoscrl} is disabled, then new text from the host
- must go somewhere so it is put at the top of the display. If the old
- text is not erased, the new text merges (nonsensically) into the old.
- If the old text is erased, then the new text is out of context. So
- keep (auto)scrolling enabled.
-
-
- 13.13.3. New Page?
-
- See ``Pages'' and ``Pages'' for explanations of pages. When the
- current page is full (the last line is finished) should the page
- scroll, or should a new page be created (leaving the previous page
- stored in the terminal's display memory). If {Autopage} is set, then
- a new page is created. Since you are probably not using pages, you
- should probably set this to off.
-
-
- 13.14. Function Keys
-
- These are the keys labeled F1, F2, etc. On older terminals they may
- be labeled PF1, PF2, etc. where the P stands for Programmable. Some
- keyboards have both. One may program (redefine) these keys to send
- out a string of user-defined bytes. They may often be easily
- "programmed" using a certain set-up menu {FKey}. On some terminals,
- one may also specify where this string is sent to when the key is
- pressed. In "normal" mode, pressing the key is just like typing the
- string at the keyboard. In "local" mode pressing the key sends it to
- the terminal (just like if the terminal was in local mode). This may
- be used to send escape sequences to the terminal so as to configure it
- in a special way. In "remote" mode, the string is always sent out the
- serial port to the host computer (even if the terminal is in local
- mode).
-
-
- 13.15. Block Mode Options
-
- Some options are only for the case of ``Block Mode''. This option is
- powerful since it provides forms and takes load off the host computer
- by transmitting in bursts. But it's more complicated to set up and is
- thus not used too much.
-
-
- 13.15.1. Forms Display
-
- In block mode some regions of the screen are for the text of forms and
- are thus write-protected "Prot" {WPRT}. Options may set the
- characters in these regions to appear dim, reverse video {WPRT Rev},
- and/or underlined {WPRT Undrln}. {WPRT Intensity} may be set to dim,
- normal, or even blank (invisible)
-
-
- 13.15.2. Send Entire Block ?
-
- Should write-protected text (the original text in the form) be sent to
- the host upon transmission of a block: {Send All} or is write-
- protected text also read-protected: {Send Erasable}
-
-
- 13.15.3. Region to Send
-
- Should the entire screen be sent or just the scrolling region? {Send
- Area}. Should the sending stop when the current cursor position is
- reached? If {Xfer Term} is set to Cursor, only the data on the screen
- up to the cursor is sent.
-
-
- 13.15.4. Block/Page terminator
-
- What is the termination symbol to be appended to a block of data?
- {Blk End} or at the end of a page {Send Term}ination.
-
-
- 13.16. Locks
-
- There are various types of Locks. One is the Locked keyboard due to
- flow control. See ``Keyboard Lock'' Another lock {Feature Lock} is
- that which prohibits the host computer from changing the terminal set-
- up by sending certain escape sequences to the terminal. Placing such
- a lock may result in unexpected behavior as application programs send
- escape sequences to the terminals that are ignored. Not all set-up
- parameters lock. Unless you have a good reason to do so, you should
- not enable such locking.
-
- A Function Key lock will prohibit the computer from redefining what a
- programmable function key sends. You may want to use this if you have
- something important programmed into the function keys.
-
-
- 13.17. Screen Saver {Scrn Saver}
-
- Also called "CRT Saver". This turns off (or dims) the screen after
- the terminal is not used for a period of time. It may prolong the
- life of the screen and save some energy. Hitting any key will usually
- restore the screen and may "execute" that key so it's best to hit the
- shift-key, etc.
-
-
- 13.18. Printer
-
- For Wyse, if there is no {Printer Attached} set it to Off. It's not
- essential to do this, but if you do it any escape sequence to send
- text to the printer (instead of the terminal) will be ignored.
-
- Setting up the printer port is about the same (usually simpler) as
- setting up the communications on the main port. There are a couple of
- options specific to the printer. Is the printer a serial or parallel
- printer? If it's parallel it should be designated as such in setup
- and connected to the parallel port on the terminal (if there is one).
- Should a FF (form feed) be sent to the printer at the end of a print
- job? If {Print Term} is set to FF, this will happen.
-
-
- 14. Computer Set-Up (Configure) Details
-
- There are various files to edit to set up the computer for terminals.
- If you're lucky, you'll only need to edit /etc/inittab. One does this
- by editing at the console (or from any working terminal).
-
-
- 14.1. Getty (used in /etc/inittab)
-
- 14.1.1. Introduction to Getty
-
- In order to have a login process run on a serial port (and the
- terminal connected to it) when the computer starts up (or switches run
- levels) a getty command must be put into the /etc/inittab file.
- Running getty from the command line may cause problems (see ``If getty
- run from command line: Programs get stopped'' to see why ). Getty
- GETs a TTY (a terminal) going. Each terminal needs its own getty
- command. There is also at least one getty command for the console in
- every /etc/inittab file. Find this and put the getty commands for the
- real terminals next to it. This file may contain sample getty lines
- for text terminals that are commented out so that all you need to do
- is to uncomment them (remove the leading #) and change a few
- arguments.
-
- The arguments which are permitted depend on which getty you use:
- Two gettys best for directly connected terminals are:
-
- 1. agetty (sometimes just called getty): Very easy to set up. No
- config files. See ``agetty''
-
- 2. ``getty (part of getty_ps)''
-
- Two gettys best for modems (avoid for directly connected terminals)
- are:
-
- 1. mgetty: the best one for modems; works for terminals too but
- inferior
-
- 2. uugetty: for modems only; part of the getty_ps package
-
- Simple gettys to use if you don't use a real text-terminal. Most
- Linux users use one of these at their monitor:
-
- 1. mingetty
-
- 2. fbgetty
-
- Your Linux distribution may come with either ps_getty or agetty for
- text-terminals. Some distributions supply neither. Unfortunately,
- they often just call it "getty" so you may need to determine which one
- you have since the arguments you put after it in /etc/inittab differ.
- Debian uses agetty (in the util-linux package). RedHat uses ps_getty
- which was found at:
-
-
- As a last resort to try to determine which getty you have, you might
- check out its executable code (usually in /sbin). ps_getty has
- /etc/gettydefs embedded in this code. To search for it, go to /sbin
- and type:
- strings getty | grep getty
- If getty is actually agetty the above will result in nothing. However
- if you have agetty typing:
- -h
-
- If you don't have the getty you want check other distributions and the
- alien program to convert between RPM and Debian packages. The source
- code may be downloaded from Getty Software
- .
-
- If you are not using modem control lines (for example if you only use
- the minimum number of 3 conductors: transmit, receive, and common
- signal ground) you should let getty know this by using a "local" flag.
- The format of this depends on which getty you use.
-
-
- 14.1.2. Getty exits after login (and can respawn)
-
- After you log in you will notice (by using "top", "ps -ax", or
- "ptree") that the getty process is no longer running. What happened
- to it? Why does getty restart again if your shell is killed? Here's
- why.
-
- After you type in your user name, getty takes it and calls the login
- program telling it your user name. The getty process is replaced by
- the login process. The login process asks for your password, checks
- it and starts whatever process is specified in your password file.
- This process is often the bash shell. If so, bash starts and replaces
- the login process. Note that one process replaces another and that
- the bash shell process originally started as the getty process. The
- implications of this will be explained below.
-
- Now in the /etc/inittab file, getty is supposed to respawn (restart)
- if killed. It says so on the line that calls getty. But if the bash
- shell (or the login process) is killed, getty respawns (restarts).
- Why? Well, both the login process and bash are replacements for getty
- and inherit the signal connections establish by their predecessors.
- In fact if you observe the details you will notice that the
- replacement process will have the same process ID as the original
- process. Thus bash is sort of getty in disguise with the same process
- ID number. If bash is killed it is just like getty was killed (even
- though getty isn't running anymore). This results in getty
- respawning.
-
- When one logs out, all the processes on that serial port are killed
- including the bash shell. This may also happen (if enabled) if a
- hangup signal is sent to the serial port by a drop of DCD voltage by
- the modem. Either the logout or drop in DCD will result in getty
- respawning. One may force getty to respawn by manually killing bash
- (or login) either by hitting the k key, etc. while in "top" or with
- the "kill" command. You will likely need to kill it with signal 9
- (which can't be ignored).
-
-
-
- 14.1.3. If getty run from command line: Programs get stopped
-
- You should normally run getty from inside /etc/inittab and not from
- the command line or else some programs running on the terminal may be
- unexpectedly suspended (stopped). Here's why (skip to the next
- section if the why is not important to you). If you start getty for
- say ttyS1 from the command line of another terminal, say tty1, then it
- will have tty1 as its "controlling terminal" even though the actual
- terminal it runs on is ttyS1. Thus it has the wrong controlling
- terminal. But if it's started inside the inittab file then it will
- have ttyS1 as the controlling terminal (correct).
-
- Even though the controlling terminal is wrong, the login at ttyS1
- works fine (since you gave ttyS1 as an argument to getty). The
- standard input and output are set to ttyS1 even though the controlling
- terminal remains tty11. Other programs run at ttyS1 may inherit this
- standard input/output (which is connected to ttyS1) and everything is
- OK. But some programs may make the mistake of trying to read from
- their controlling terminal (tty1) which is wrong. Now tty1 may think
- that these programs are being run in the background by tty1 so an
- attempt to read from tty1 (it should have been ttyS1) results in
- stopping the process that attempted to read. (A background process is
- not allowed to read from its controlling terminal.). You may see a
- message something like: "[1]+ Stopped" on the screen. At this point
- you are stuck since you can't interact with a process which is trying
- to communicate with you via the wrong terminal. Of course to escape
- from this you can go to another terminal and kill the process, etc.
-
-
- 14.1.4. agetty (may be named getty)
-
- An example line in /etc/inittab:
-
-
- S1:23:respawn:/sbin/getty -L 19200 ttyS1 vt102
-
-
-
- S1 is from ttyS1. 23 means that getty is run upon entering run levels
- 2 or 3. respawn means that if getty (or a process that replaced it
- such as bash) is killed, getty will automatically start up (respawn)
- again. /sbin/getty is the getty command. The -L means Local (ignore
- modem control signals). -h (not shown in the example) enables hard
- ware flow control (same as stty crtscts). 19200 is the baud rate.
- ttyS1 means /dev/ttyS1 (COM2 in MS-DOS). vt102 is the type of termi
- nal and this getty will set the environment variable TERM to this
- value. There are no configuration files. Type "init q" on the com
- mand line after editing getty and you should see a login prompt.
-
-
- 14.1.4.1. Agetty's auto-detection of parity problems
-
- The agetty program will attempt to auto-detect the parity set inside
- the terminal (including no parity). It doesn't support 8-bit data
- bytes plus 1-bit parity. See ``8-bit data bytes (plus parity)''. If
- you use stty to set parity, agetty will automatically unset it since
- it initially wants the parity bit to come thru as if it was a data
- bit. This is because it needs to get the last bit (possibly a parity
- bit) as you type your login-name so that it can auto-detect parity.
- Thus if you use parity, enable it only inside the text-terminal and
- let agetty auto-detect it and set it at the computer. If your
- terminal supports received parity, the login prompt will look garbled
- until you type something so that getty can detect the parity. The
- garbled prompt will deter visitors, etc. from trying to login. That
- could be just what you want.
-
- There is sometimes a problem with auto detection of parity. This
- happens because after you first type your login name, agetty starts
- the login program to finish logging you in. Unfortunately, the login
- program can't detect parity so if the getty program failed to
- determine the parity then login will not be able to determine it
- either. If the first login attempt fails, login will let you try
- again, etc. (all with the parity set wrong). Eventually, after a
- number of failed attempts to login (or after a timeout) agetty will
- start up again and start the login sequences all over again. Once
- getty is running again, it may be able to detect the parity on the
- second try so everything may then work OK.
-
- With wrong parity, the login program can't correctly read what you
- type and you can't log in. If your terminal supports received parity,
- you will continue to see a garbled screen. If getty fails to detect
- parity an /etc/issue file is usually dumped to the screen just before
- the before the prompt, so more garbled words may appear on the screen.
-
- Why can't agetty detect parity by the first letter typed? Here's an
- example: Suppose it detects an 8-bit byte with its parity bit 0 (high-
- order bit) and with an odd number of 1-bits. What parity is it?
- Well, the odd number of 1 bits implies that it's odd parity. But it
- could also just be an 8-bit character with no parity. There's no way
- so far to determine which. But so far we have eliminated the
- possibility of even parity. The detection of parity thus proceeds by
- a process of elimination.
-
- If the next byte typed is similar to the first one and also only
- eliminates the possibility of even parity, it's still impossible to
- determine parity. This situation can continue indefinitely and in
- rare cases login will fail until you change your login-name. If
- agetty finds a parity bit of 1 it will assume that this is a parity
- bit and not a high-order bit of an 8-bit character. It thus assumes
- that you don't use meta-characters (high bit set) in your user name
- (i.e that your name is in ASCII).
-
- One may get into a "login loop" in various ways. Suppose you only
- type a single letter or two for your login name and then hit return.
- If these letters are not sufficient for parity detection, then login
- runs before parity has been detected. Sometimes this problem happens
- if you don't have the terminal on and/or connected when agetty first
- starts up.
-
- If you get stuck in this "login loop" a way out of it is to hit the
- return key several times until you get the getty login prompt.
- Another way is to just wait a minute or so for a timeout. Then the
- getty login prompt will be put on the screen by the getty program and
- you may try again to log in.
-
-
- 14.1.4.2. 8-bit data bytes (plus parity)
-
- Unfortunately, agetty can't detect this parity. As of late 1999 it
- has no option for disabling the auto-detection of parity and thus will
- detect incorrect parity. The result is that the login process will be
- garbled and parity will be set wrong. Thus it doesn't seem feasible
- to try to use 8-bit data bytes with parity.
-
-
- 14.1.5. getty (part of getty_ps)
-
- (Most of this is from the old Serial-HOWTO by Greg Hankins)
- For this getty one needs to both put entries in a configuration file
- and add an entry in /etc/inittab. Here are some example entries to
- use for your terminal that you put into the configuration file
- /etc/gettydefs.
-
-
-
- # 38400 bps Dumb Terminal entry
- DT38400# B38400 CS8 CLOCAL # B38400 SANE -ISTRIP CLOCAL #@S @L login: #DT38400
-
- # 19200 bps Dumb Terminal entry
- DT19200# B19200 CS8 CLOCAL # B19200 SANE -ISTRIP CLOCAL #@S @L login: #DT19200
-
- # 9600 bps Dumb Terminal entry
- DT9600# B9600 CS8 CLOCAL # B9600 SANE -ISTRIP CLOCAL #@S @L login: #DT9600
-
-
-
- Note that the DT38400, DT19200, etc. are just labels and must be the
- same that you use in /etc/inittab.
-
- If you want, you can make getty print interesting things in the login
- banner. In my examples, I have the system name and the serial line
- printed. You can add other things:
-
-
- @B The current (evaluated at the time the @B is seen) bps rate.
- @D The current date, in MM/DD/YY.
- @L The serial line to which getty is attached.
- @S The system name.
- @T The current time, in HH:MM:SS (24-hour).
- @U The number of currently signed-on users. This is a
- count of the number of entries in the /etc/utmp file
- that have a non-null ut_name field.
- @V The value of VERSION, as given in the defaults file.
- To display a single '@' character, use either '\@' or '@@'.
-
-
-
- When you are done editing /etc/gettydefs, you can verify that the
- syntax is correct by doing:
-
-
- linux# getty -c /etc/gettydefs
-
-
-
- Make sure there is no other getty or uugetty config file for the
- serial port that your terminal is attached to such as
- (/etc/default/{uu}getty.ttySN or /etc/conf.{uu}getty.ttySN), as this
- will probably interfere with running getty on a terminal. Remove such
- conflicting files if they exits.
-
- Edit your /etc/inittab file to run getty on the serial port
- (substituting in the correct information for your environment - port,
- speed, and default terminal type):
-
-
- S1:23:respawn:/sbin/getty ttyS1 DT9600 vt100
-
-
-
- Restart init:
-
-
- linux# init q
-
-
-
- At this point, you should see a login prompt on your terminal. You
- may have to hit return to get the terminal's attention.
-
-
- 14.1.6. mgetty
-
- The "m" stands for modem. This program is primarily for modems and as
- of mid 2000 it will require recompiling to use it for text-terminals
- (unless you use hardware flow control --and that usually requires a
- hand-made cable). For the documentation for directly connected
- terminals see the "Direct" section of the manual: mgetty.texi.
-
- Look at the last lines of /etc/mgetty/mgetty.config for an example of
- configuring it for a terminal. Unless you say "toggle-dtr no" it will
- think that you have a modem and drop (negate) the DTR pin at the PC in
- a vain attempt to reset the non-existent modem. In contrast to other
- gettys, mgetty will not attach itself to a terminal until someone hits
- any key of that terminal so you'll see a ? for the terminal in top or
- ps until this happens. The logs in /var/log/mgetty/ may show a few
- warning messages which are only applicable to modems which you may
- ignore.
-
- Here's an example of the simple line you put in /etc/inittab:
-
-
-
- s1:23:respawn:/sbin/mgetty -r ttyS1
-
-
-
- 14.2. Stty & Setserial
-
- There is both a "stty" command and a "setserial" command for setting
- up the serial ports. Some (or all) of the needed stty settings can
- be done via getty and there may be no need to use setserial so you may
- not need to use either command. These two commands (stty and
- setserial) set up different aspects of the serial port. Stty does the
- most while setserial configures the low-level stuff such as interrupts
- and port addresses. To "save" the settings, these commands must be
- written in certain files (shell scripts) which run each time the
- computer starts up. Distributions of Linux often supply a shell
- script which runs setserial but seldom supply one which runs stty
- since on seldom need it.
-
-
- 14.3. Setserial
-
- This part is in 3 HOWTOs: Modem, Serial, and Text-Terminal. There are
- some minor differences, depending on which HOWTO it appears in.
-
-
- 14.3.1. Important information
-
-
- If you have a Laptop (PCMCIA) don't use setserial until you read
- ``Laptops: PCMCIA''.
-
-
- 14.3.2. Introduction
-
- setserial is a program which allows you (or a shell script) to talk to
- the serial device driver software. But there's also another program
- tt/stty/ that also deals with the serial port and is used for setting
- the port speed, etc.
-
- setserial deals with the lower-level configuring of the serial port,
- such as dealing with IRQs (such as 5), port addresses (such as 3f8),
- and the like. A major problem with it is that it can't configure the
- serial port hardware: It can't set the IRQ or port addresses into the
- hardware. Furthermore, when it reports the configuration of the
- hardware, it's sometimes wrong since it doesn't acuually probe the
- hardware unless you specifically tell it to. Actually, it's right
- most all the time but if you're having trouble getting a serial port
- to work, then there's a fair chance it's wrong.
-
- In olden days, when the IRQ and port address was set by jumpers on the
- serial card, one would use setserial to tell the driver how these
- jumpers were set. Today, when plug-and-play methods detect how the
- jumper-less serial port is set, setserial is not really needed anymore
- unless you're having problems or using old hardware. Furthermore, if
- the configuration file used by setserial is wrong, then there's
- trouble. In this case, if you use setserial to try ot find out how
- the port is configured, it may just repeat the incorrect information
- in the configuration file.
-
- setserial can sometimes be of help to find a serial port. But it's
- only of use if you know the port address and use the right options.
- For modern port's, there's usually better ways to look for them.
-
- Thus the name setserial is somewhat of a misnomer since it doesn't set
- the I/O address nor IRQ in the hardware, it just "sets" them in the
- driver software. And the driver naively believes that what setserial
- tells it even if it conflicts with what the driver has found by using
- plug-and-play methods. Too bad that it fails to at least issue a
- warning message for such a conflict. Since the device driver is
- considered to be part of the kernel, the word "kernel" is often used
- in other documentation with no mention made of any "serial driver".
-
- Some distributions (and versions) set things up so that setserial is
- run at boot-time by an initialization shell script (in the /etc
- directory tree). But the configuration file which this script uses
- may be either in the /etc tree or the /var tree. In some cases, if
- you want setserial to run at boottime, you may have to take some
- action. setserialwill not work without either serial support built
- into the kernel or loaded as a module. The module may get loaded
- automatically if you (or a script) attempt to use setserial.
-
- While setserial can be made to probe the hardware I0 port addresses to
- try to determine the UART type and IRQ, this has severe limitations.
- See ``Probing''. It can't set the IRQ or the port address in the
- hardware of PnP or PCI serial ports (but the plug-and-play features of
- the serial driver may do this). It also can't directly read the PnP
- data stored in configuration registers in the hardware. But since the
- device driver can read these registers, setserial could be telling you
- what's in them, or it could be telling you what setserial had
- previously (and perhaps erroneously) told the driver. There's no way
- to know for sure without doing some other checks.
-
- The serial driver (for Linux 2.4+) looks for a few "standard" legacy
- serial ports, for PnP ports on the ISA bus, and for all supported port
- hardware on the PCI bus. If it finds these, then there's no need to
- use setserial. The driver doesn't probe for legacy IRQs and may get
- these wrong.
-
- Besides the man page for setserial, check out info in
- /usr/doc/setserial.../ or /usr/share/doc/setserial. This should tell
- you how setserial is handled for your distribution of Linux. While
- setserial behaves the same in all distributions, the scripts for
- running it, how to configure such scripts (including automatic
- configuration), and the names and locations of the script files, etc.,
- are all distribution-dependent. If your serial port is Plug-and-Play
- you may need to consult other HOWTOs such as Plug-and-Play or Serial.
-
-
- 14.3.3. Serial module unload
-
- If a serial module gets unloaded, the changes previously made by
- setserial will be forgotten by the driver. But while the driver
- forgets it, a script provided by the distribution may save it in a
- file somewhere so that it can the restored if the module is reloaded.
-
-
-
- 14.3.4. Giving the setserial command
-
- Remember, that setserial can't set any I/O addresses or IRQs in the
- hardware. That's done either by plug-and-play software (run by the
- driver) or by jumpers for legacy serial ports. Even if you give an
- I/O address or IRQ to the driver via setserial it will not set such
- values and assumes that they have already been set. If you give it
- wrong values, the serial port will not work right (if at all).
-
- For legacy ports, if you know the I/O address but don't know the IRQ
- you may command setserial to attempt to determine the IRQ.
-
- You can see a list of possible commands by just typing setserial with
- no arguments. This fails to show you the one-letter options such as
- -v for verbose which you should normally use when troubleshooting.
- Note that setserial calls an IO address a "port". If you type:
-
-
- setserial -g /dev/ttyS*
-
-
-
- you'll see some info about how the device driver is configured for
- your ports. Note that where it says "UART: unknown" it probably means
- that no uart exists. In other words, you probably have no such serial
- port and the other info shown about the port is meaningless and should
- be ignored. If you really do have such a serial port, setserial
- doesn't recognize it and that needs to be fixed.
-
- If you add -a to the option -g you will see more info although few
- people need to deal with (or understand) this additional info since
- the default settings you see usually work fine. In normal cases the
- hardware is set up the same way as "setserial" reports. But if you
- are having problems there is a good chance that setserial has it
- wrong. In fact, you can run "setserial" and assign a purely
- fictitious I/O port address, any IRQ, and whatever uart type you would
- like to have. Then the next time you type "setserial ..." it will
- display these bogus values you've supplied to the driver. They will
- also be officially registered with the kernel as displayed (at the top
- of the screen) by the "scanport" command (Debian). Of course the
- serial port driver will not work correctly (if at all) if you attempt
- to use such a port. Thus, when giving parameters to setserial,
- "anything goes". Well almost. If you assign one port a base address
- that is already assigned (such as 3e8) it may not accept it. But if
- you use 3e9 it will accept it. Unfortunately 3e9 is actually assigned
- since it is within the range starting at base address 3e8. Thus the
- moral of the story is to make sure your data is correct before
- assigning resources with setserial.
-
-
- 14.3.5. Configuration file
-
- While assignments made by setserial are lost when the PC is powered
- off, a configuration file may restore them when the PC is started up
- again. In newer versions, what you change by setserial might get
- automatically saved to a configuration file. When setserial runs it
- uses the info from the the configuration file. In Debian there are 4
- options for use of this configuration file:
-
-
- 1. Don't use this file at all. At each boot, the serial driver alone
- detects the ports and setserial doesn't ever run. ("kernel"
- option)
-
- 2. Save what setserial reports when the system is first shutdown and
- put it in the configuration file. After that, don't ever make any
- changes to the configuration file, even if someone has made changes
- by running the setserial command on the command line and then shuts
- down the system. ("autosave-once" option)
-
- 3. At every shutdown, save whatever setserial detects to the
- configuration file. ("autosave" option)
-
- 4. Manually edit the configuration file to set the configuration.
- Don't ever do any automatic saves to it. ("manual" option)
-
- In olden days (perhaps before 2000), there wasn't any configuration
- file and the configuration was manually set (hard coded) inside the
- shell script that ran setserial. See ``Edit a script (prior to
- version 2.15)''.
-
-
-
- 14.3.6. Probing
-
- You probe for a port with setserial only when you suspect that it has
- been enabled (by PnP methods, the BIOS, jumpers, etc.). Otherwise
- setserial probing will never find it since its address doesn't exist.
- Probling is where the software looks for a port at specified I/O
- addresses. Prior to probing with "setserial", one may run the
- "scanport" (Debian) command to check all possible ports in one scan.
- It makes crude guesses as to what is on some ports but doesn't
- determine the IRQ. It's a fast first start. It may hang your PC but
- so far it's worked fine for me. Note that non-Debian distributions
- don't seem to supply "scanport". Is there another scan program?
-
- With appropriate options, setserial can probe (at a given I/O address)
- for a serial port but you must guess the I/O address. If you ask it
- to probe for /dev/ttyS2 for example, it will only probe at the address
- it thinks ttyS2 is at (2F8). If you tell setserial that ttyS2 is at a
- different address, then it will probe at that address, etc. See
- ``Probing''
-
- The purpose of such probing is to see if there is a uart there, and if
- so, what its IRQ is. Use setserial mainly as a last resort as there
- are faster ways to attempt it such as wvdialconf to detect modems,
- looking at very early boot-time messages, or using pnpdump --dumpregs,
- or lspci -vv. But if you want to detect hardware with setserial use
- for example :
- /dev/ttyS2 -v autoconfig
- If the resulting message shows a uart type such as 16550A, then you're
- OK. If instead it shows "unknown" for the uart type, then there is
- supposedly no serial port at all at that I/O address. Some cheap
- serial ports don't identify themselves correctly so if you see
- "unknown" you still might have a serial port there.
-
- Besides auto-probing for a uart type, setserial can auto-probe for
- IRQ's but this doesn't always work right either. In one case it first
- gave the wrong irq but when the command was repeated it found the
- correct irq. In versions of setserial >= 2.15, the results of your
- last probe test could be automatically saved and put into a
- configuration file such as /etc/serial.conf or
- /var/lib/setserial/autoserial.conf for Debian. This will be used next
- time you start Linux.
-
- It may be that two serial ports both have the same IO address set in
- the hardware. Of course this is not normally permitted for the ISA
- bus but it sometimes happens anyway. Probing detects one serial port
- when actually there are two. However if they have different IRQs,
- then the probe for IRQs may show IRQ = 0. For me, it only did this if
- I first used setserial to give the IRQ a fictitious value.
-
-
- 14.3.7. Boot-time Configuration
-
- While setserial may run via an initialization script, something akin
- to setserial also runs earlier when the serial module is loaded (or
- when the kernel starts the built-in serial driver if it was compiled
- into the kernel). Thus when you watch the start-up messages on the
- screen it may look like it ran twice, and in fact it has.
-
- If the first message is for a legacy port, the IRQs shown may be wrong
- since it didn't probe for IRQs. If there is a second report of serial
- ports, it may the result of a script such as /etc/init.d/setserial.
- It usually does no probing and thus could be wrong about how the
- hardware is actually set. It only shows configuration data that got
- saved in a configuration files. The old method, prior to setserial
- 2.15, was to manually write such data directly into the script.
-
- When the kernel loads the serial module (or if the "module equivalent"
- is built into the kernel) then all supported PnP ports are detected.
- For legacy (non-PnP) ports, only ttyS{0-3} are auto-detected and the
- driver is set to use only IRQs 4 and 3 (regardless of what IRQs are
- actually set in the hardware). No probing is done for IRQs but it's
- possible to do this manually. You see this as a boot-time message
- just as if setserial had been run.
-
- To correct possible errors in IRQs (or for other reasons) there may be
- a script file somewhere that runs setserial. Unfortunately, if this
- file has some IRQs wrong, the kernel will still have incorrect info
- about the IRQs. This file is usually part of the initialization done
- at boot-time. Whether it runs or not depends on how you (and/or your
- distribution) have set things up. It may also depends on the
- runlevel.
-
- Before modifying a configuration file, you can test out a "proposed"
- setserial command by just typing it on the command line. In some
- cases the results of this use of setserial will automatically get
- saved in /etc/serial.conf (or autoserial.conf) when you shutdown. So
- if it worked OK (and solved your problem) then there's no need to
- modify any configuration file. See ``Configuration method using
- /etc/serial.conf, etc.''.
-
-
- 14.3.8. Edit a script (required prior to version 2.15)
-
- This is how it was done prior to setserial 2.15 (1999) The objective
- was to modify (or create) a script file in the /etc tree that runs
- setserial at boot-time. Most distributions provided such a file (but
- it may not have initially resided in the /etc tree).
-
- So prior to version 2.15 (1999) it was simpler. All you did was edit
- a script. There was no /etc/serial.conf file (or the like) to
- configure setserial. Thus you needed to find the file that runs
- "setserial" at boot time and edit it. If it didn't exist, you needed
- to create one (or place the commands in a file that ran early at boot-
- time). If such a file was currently being used it's likely was
- somewhere in the /etc directory-tree. But Redhat <6.0 has supplied it
- in /usr/doc/setserial/ but you need to move it to the /etc tree before
- using it.
-
- The script /etc/rc.d/rc.serial was commonly used in the past. The
- Debian distribution used /etc/rc.boot/0setserial. Another file once
- used was /etc/rc.d/rc.local but it's may not have run early enough.
- It's was reported that other processes may try to open the serial port
- before rc.local ran resulting in serial communication failure. Later
- on it's most likely was found in /etc/init.d/ but wasn't normally
- intended to be edited.
-
- If such a file was supplied, it likely contained a number of
- commented-out examples. By uncommenting some of these and/or
- modifying them, you could set things up correctly. It was important
- use a valid path for setserial, and a valid device name. You could do
- a test by executing this file manually (just type its name as the
- super-user) to see if it works right. Testing like this was a lot
- faster than doing repeated reboots to get it right.
-
- For versions >= 2.15 (provided your distribution implemented the
- change, Redhat didn't as first) it may be more tricky to do since the
- file that runs setserial on startup, /etc/init.d/setserial or the like
- was not intended to be edited by the user. See ``Configuration method
- using /etc/serial.conf, etc.''.
-
- An example line in such a script was"
-
- /sbin/setserial /dev/ttyS3 irq 5 uart 16550A skip_test
-
-
-
- or, if you wanted setserial to automatically determine the uart and
- the IRQ for ttyS3 you would have used something like this:
-
-
-
- /sbin/setserial /dev/ttyS3 auto_irq skip_test autoconfig
-
-
-
- This was done for every serial port you wanted to auto configure,
- using a device name that really does exist on your machine. In some
- cases it didn't work right due to the hardware.
-
-
- 14.3.9. Configuration method using /etc/serial.conf, etc.
-
- Prior to setserial version 2.15 (1999), the way to configure setserial
- was to manually edit the shell-script that ran setserial at boot-time.
- See ``Edit a script (before version 2.15)''. Today the script and
- configuration file are two different files instead of one. This
- shell-script is not edited but gets its data from a configuration file
- such as /etc/serial.conf (or /var/lib/setserial/autoserial.conf).
-
- Furthermore you may not even need to edit serial.conf (or the like)
- because using the "setserial" command on the command line may
- automatically cause serial.conf to be edited appropriately. This was
- done so that you don't need to edit any file in order to set up (or
- change) what setserial does each time that Linux is booted.
-
- What often happens is this: When you shut down your PC the script
- that ran "setserial" at boot-time is run again, but this time it only
- does what the part for the "stop" case says to do: It uses
- "setserial" to find out what the current state of "setserial" is, and
- it puts that info into the serial configuration file such as
- serial.conf. Thus when you run "setserial" to change the serial.conf
- file, it doesn't get changed immediately but only when and if you shut
- down normally.
-
- Now you can perhaps guess what problems might occur. Suppose you
- don't shut down normally (someone turns the power off, etc.) and the
- changes don't get saved. Suppose you experiment with "setserial" and
- forget to run it a final time to restore the original state (or make a
- mistake in restoring the original state). Then your "experimental"
- settings are saved. There's an option to avoid this in Debian known
- as "AUTOSAVE-ONCE" which will be discussed later on.
-
- If you manually edit serial.conf, then your editing is destroyed when
- you shut down because it gets changed back to the state of setserial
- at shutdown. There is a way to disable the changing of serial.conf at
- shutdown and that is to remove "###AUTOSAVE###" or the like from first
- line of serial.conf. In the Debian distribution, the removal of
- "###AUTOSAVE###" from the first line was once automatically done after
- the first time you shutdown just after installation. To retain this
- effect the "AUTOSAVE-ONCE" option was created which only does a save
- when time the system is shut down for the first time (just after you
- install or update the setserial program).
-
- The file most commonly used to run setserial at boot-time (in
- conformance with the configuration file) is now /etc/init.d/setserial
- (Debian) or /etc/init.d/serial (Redhat), or etc., but it should not
- normally be edited. For 2.15, Redhat 6.0 just had a file
- /usr/doc/setserial-2.15/rc.serial which you have to move to
- /etc/init.d/ if you want setserial to run at boot-time.
-
- To disable a port, use setserial to set it to "uart none". This will
- not be saved. The format of /etc/serial.conf appears to be just like
- that of the parameters placed after "setserial" on the command line
- with one line for each port. If you don't use autosave, you may edit
- /etc/serial.conf manually.
-
- In order to force the current settings set by setserial to be saved to
- the configuration file (serial.conf) without shutting down, do what
- normally happens when you shutdown: Run the shell-script
- /etc/init.d/{set}serial stop. The "stop" command will save the
- current configuration but the serial ports still keep working OK.
-
- In some cases you may wind up with both the old and new configuration
- methods installed but hopefully only one of them runs at boot-time.
- Debian labeled obsolete files with "...pre-2.15".
-
-
- 14.3.10. IRQs
-
- By default, both ttyS0 and ttyS2 will share IRQ 4, while ttyS1 and
- ttyS3 share IRQ 3. But while sharing serial interrupts (using them in
- running programs) is OK for the PCI bus, it's not permitted for the
- ISA bus unless you: 1. have kernel 2.2 or better, and 2. you've
- complied in support for this, and 3. your serial hardware supports it.
- See Serial-HOWTO: Interrupt sharing and Kernels 2.2+.
-
-
- If you only have two serial ports, ttyS0 and ttyS1, you're still OK
- since IRQ sharing conflicts don't exist for non-existent devices.
-
- If you add a legacy internal modem (without plug-and-play) and retain
- ttyS0 and ttyS1, then you should attempt to find an unused IRQ and set
- it both on your serial port (or modem card) and then use setserial to
- assign it to your device driver. If IRQ 5 is not being used for a
- sound card, this may be one you can use for a serial port for a modem.
-
-
- 14.3.11. Laptops: PCMCIA
-
- If you have a Laptop, read PCMCIA-HOWTO for info on the serial
- configuration. For serial ports on the motherboard, setserial is used
- just like it is for a desktop. But for PCMCIA cards (such as a modem)
- it's a different story. The configuring of the PCMCIA system should
- automatically run setserial so you shouldn't need to run it. If you
- do run it (by a script file or by /etc/serial.conf) it might be
- different and cause trouble. The autosave feature for serial.conf
- shouldn't save anything for PCMCIA cards (but Debian did until
- 2.15-7). Of course, it's always OK to use setserial to find out how
- the driver is configured for PCMCIA cards.
-
-
-
- 14.4. Stty
-
- 14.4.1. Introduction
-
- stty does much of the configuration of the serial port but since
- application programs (and the getty program) often handle it, you may
- not need to use it much. It's handy if you're having problems or want
- to see how the port is set up. Try typing ``stty -a'' at your
- terminal/console to see how it's now set. Also try typing it without
- the -a (all) for a short listing which shows how it's set different
- than normal. Don't try to learn all the setting unless you want to
- become a serial guru. Most of the defaults should work OK and some of
- the settings are needed only for certain obsolete dumb terminals made
- in the 1970's.
-
- stty is documented in the man pages with a more detailed account in
- the info pages. Type "man stty" or "info stty".
-
- Whereas setserial only deals with actual serial ports, stty is used
- both for serial ports and for virtual terminals such as the standard
- Linux text interface at a PC monitor. For the PC monitor, many of the
- stty settings are meaningless. Changing the baud rate, etc. doesn't
- appear to actually do anything.
-
- Here are some of the items stty configures: speed (bits/sec), parity,
- bits/byte, # of stop bits, strip 8th bit?, modem control signals, flow
- control, break signal, end-of-line markers, change case, padding, beep
- if buffer overrun?, echo what you type to the screen, allow background
- tasks to write to terminal?, define special (control) characters (such
- as what key to press for interrupt). See the stty man or info page
- for more details. Also see the man page: termios which covers the
- same options set by stty but (as of mid 1999) covers features which
- the stty man page fails to mention. For use of some special
- characters see ``Special (Control) Characters''
-
- With some implementations of getty (getty_ps package), the commands
- that one would normally give to stty are typed into a getty
- configuration file: /etc/gettydefs. Even without this configuration
- file, the getty command line may be sufficient to set things up so
- that you don't need stty.
-
- One may write C programs which change the stty configuration, etc.
- Looking at some of the documentation for this may help one better
- understand the use of the stty command (and its many possible
- arguments). Serial-Programming-HOWTO is useful. The manual page:
- termios contains a description of the C-language structure (of type
- termios) which stores the stty configuration in computer memory. Many
- of the flag names in this C-structure are almost the same (and do the
- same thing) as the arguments to the stty command.
-
-
- 14.4.2. Flow control options
-
- To set hardware flow control use "crtscts". For software flow control
- there are 3 settings: ixon, ixoff, and ixany.
-
- ixany: Mainly for terminals. Hitting any key will restarts the flow
- after a flow-control stop. If you stop scrolling with the "stop
- scroll" key (or the like) then hitting any key will resume scrolling.
- It's seldom needed since hitting the "scroll lock" key again will do
- the same thing.
-
- ixon: Enables the port to listen for Xoff and to stop transmitting
- when it gets an Xoff. Likewise, it will resume transmitting if it
- gets an Xon.
-
- ixoff: enables the port to send the Xoff signal out the transmit line
- when its buffers in main memory are nearly full. It protects the
- device where the port is located from being overrun.
-
- For a slow dumb terminal (or other slow device) connected to a fast
- PC, it's unlikely the the PC's port will be overrun. So you seldom
- actually need to enable ixoff. But it's often enabled "just in case".
-
-
-
- 14.4.3. Using stty at a "foreign" terminal
-
- Using stty to configure the terminal that you are currently using is
- easy. Doing it for a different (foreign) terminal or serial port may
- be impossible. For example, let's say you are at the PC monitor
- (tty1) and want to use stty to deal with the serial port ttyS2. Prior
- to about 2000 you needed to use the redirection operator "<". After
- 2000 (provided your version of setserial is >= 1.17 and stty >= 2.0)
- there is a better method using the -F option. This will work when the
- old redirection method fails. Even with the latest versions be warned
- that if there is a terminal on ttyS2 and a shell is running on that
- terminal, then what you see will likely be deceptive and trying to set
- it will not work. See ``Two interfaces at a terminal'' to understand
- it.
-
- The new method is ``stty -F /dev/ttyS2 ...'' (or --file instead of F).
- If ... is -a it displays all the stty settings. The old redirection
- method (which still works in later versions) is to type ``stty ...
- ). This is
- likely due to the port being stuck because it's waiting for one of the
- modem control lines to be asserted. For example, unless you've set
- "clocal" to ignore modem control lines, then if no CD signal is
- asserted the port will not open and stty will not work for it (unless
- you use the newer -F option). A similar situation seems to exist for
- hardware flow control. If the cable for the port doesn't even have a
- conductor for the pin that needs to be asserted then there is no easy
- way to stop the hang.
-
- One way to try to get out of the above hang is to use the newer -F
- option and set "clocal" and/or "crtscts" as needed. If you don't have
- the -F option then you may try to run some program (such as minicom)
- on the port that will force it to operate even if the control lines
- say not to. Then hopefully this program might set the port so it
- doesn't need the control signal in the future in order to open: clocal
- or -crtscts. To use "minicom" to do this you likely will have to
- reconfigure minicom and then exit it and restart it. Instead of all
- this bother, it may be simpler to just reboot the PC.
-
- The old redirection method makes ttyS2 the standard input to stty.
- This gives the stty program a link to the "file" ttyS2 so that it may
- "read" it. But instead of reading the bytes sent to ttyS2 as one
- might expect, it uses the link to find the configuration settings of
- the port so that it may read or change them. Some people tried to use
- ``stty ... > /dev/ttyS2'' to set the terminal. This will not do it.
- Instead, it takes the message normal displayed by the stty command for
- the terminal you are on (say tty1) and sends this message to ttyS2.
- But it doesn't change any settings for ttyS2.
-
-
- 14.4.4. Two interfaces at a terminal
-
- When using a shell (such as bash) with command-line-editing enabled
- there are two different terminal interfaces (what you see when you
- type stty -a). When you type in modern shells at the command line you
- have a temporary "raw" interface (or raw mode) where each character is
- read by the command-line-editor as you type it. Once you hit the
- key, the command-line-editor is exited and the terminal
- interface is changed to the nominal "cooked" interface (cooked mode)
- for the terminal. This cooked mode lasts until the next prompt is
- sent to the terminal (which is only a small fraction of a second).
- Note that one never gets to type anything to this cooked mode but what
- was typed in raw mode gets executed while in cooked mode.
-
- When a prompt is sent to the terminal, the terminal goes from "cooked"
- to "raw" mode (just like it does when you start an editor since you
- are starting the command-line editor). The settings for the "raw"
- mode are based only on the basic settings taken from the "cooked"
- mode. Raw mode keeps these setting but changes several other settings
- in order to change the mode to "raw". It is not at all based on the
- settings used in the previous "raw" mode. Thus if one uses stty to
- change settings for the raw mode, such settings will be permanently
- lost as soon as one hits the key at the terminal that has
- supposedly been "set".
-
- Now when one types stty to look at the terminal interface, one may
- either get a view of the cooked mode or the raw mode. You need to
- figure out which one you're looking at. It you use stty from another
- (foreign) terminal then you will see the raw mode settings. Any
- changes made will only be made to the raw mode and will be lost when
- someone presses at the terminal you tried to "set". But if
- you type a stty command at your terminal (without the -F option or
- redirection) and then hit it's a different story. The
- puts the terminal in cooked mode. Your changes are saved and
- will still be there when the terminal goes back into raw mode (unless
- of course it's a setting not allowed in raw mode).
-
- This situation can create problems. For example, suppose you corrupt
- your terminal interface. To restore it you go to another terminal and
- "stty -F dev/ttyS1 sane" (or the like). It will not work! Of course
- you can try to type "stty sane ..." at the terminal that is corrupted
- but you can't see what you typed. All the above not only applies to
- dumb terminals but to virtual terminals used on a PC Monitor as well
- as to the terminal windows in X. In other words, it applies to almost
- everyone who uses Linux.
-
- Luckily, when you start up Linux, any file that runs stty at boot-time
- will likely deal with a terminal (or serial port with no terminal)
- that has no shell running on it so there's no problem for this special
- case.
-
-
- 14.4.5. Where to put the stty command ?
-
- Should you need to have stty set up the serial interface each time the
- computer starts up then you need to put the stty command in a file
- that will be executed each time the computer is started up (Linux
- boots). It should be run before the serial port is used (including
- running getty on the port). There are many possible places to put it.
- If it gets put in more than one place and you only know about (or
- remember) one of those places, then a conflict is likely. So make
- sure to document what you do.
-
- One place to put it would be in the same file that runs setserial when
- the system is booted. The location is distribution and version
- dependent. It would seem best to put it after the setserial command
- so that the low level stuff is done first. If you have directories in
- the /etc tree where every file in them is executed at boot-time
- (System V Init) then you could create a file named "stty" for this
- purpose.
-
-
- 14.5. Terminfo & Termcap (brief)
-
- See ``Terminfo and Termcap (detailed)'' for a more detailed discussion
- of termcap. Many application programs that you run use the terminfo
- (formerly termcap) data base. This has an entry (or file) for each
- model or type (such as vt100) of terminal and tells what the terminal
- can do, what codes to send for various actions, and what codes to send
- to the terminal to initialize it.
-
- Since many terminals (and PC's also) can emulate other terminals and
- have various "modes" of operation, there may be several terminfo
- entries from which to choose for a given physical terminal. They
- usually will have similar names. The last parameter of getty (for
- both agetty and getty_ps) should be the terminfo name of the terminal
- (or terminal emulation) that you are using (such as vt100).
-
- The terminfo does more than just specify what the terminal is capable
- of doing and disclose what codes to send to the terminal to get it to
- do those things. It also specifies what "bold" will look like (will
- it be reverse video or will it be high intensity, etc.), what the
- cursor will look like, if the letters will be black, white, or some
- other color, etc. In PC terminology these are called "preferences".
- It also specifies initialization codes to send to the terminal
- (analogous to the init strings sent to modems). Such strings are not
- automatically sent to the terminal by Linux. See ``Init String''. If
- you don't like the way the display on the screen looks and behaves you
- may need to edit (and then update) the terminfo (or termcap) file.
- See ``Terminfo Compiler (tic)'' for how to update.
-
-
- 14.6. Setting TERM and TERMINFO
-
- These are two environment variables for terminals: TERM and TERMINFO,
- but you may not need to do anything about them. TERM must always be
- set to the type of the terminal you are using (such as vt100). If
- you don't know the type (name) see ``What is the terminfo name of my
- terminal ?''. TERMINFO contains the path to the terminfo data base,
- but may not be needed if the database is in a default location (or
- TERMINFO could be set automatically by a file that comes with your
- distribution of Linux). You may want to look at `` Compiled database
- locations''.
-
- Fortunately, the getty program usually sets TERM for you just before
- login. It just uses the terminal type that was specified on getty's
- command line (in /etc/inittab). This permits application programs to
- find the name of your terminal and then look up the terminal
- capabilities in the terminfo data base. See ``TERM Variable'' for
- more details on TERM.
-
- If your terminfo data base can't be found you may see an error message
- about it on your terminal. If this happens it's time to check out
- where terminfo resides and set TERMINFO if needed. You may find out
- where the terminfo database is by searching for a common terminfo file
- such as "vt100" using the "locate" command. Make sure that your
- terminal is in this database. An example of setting TERMINFO is:
- export TERMINFO=/usr/share/terminfo (put this in /etc/profile or the
- like). If the data for your terminal in this data base is not to your
- liking, you may need to edit it. See ``Terminfo & Termcap (brief)''.
-
-
- 14.6.1. What is the terminfo name of my terminal ?
-
- You need the exact name in order to set the TERM environment variable
- or to give to getty. The same name should be used by both the termcap
- and terminfo databases so you only need to find it once. A terminal
- usually has alias names but if more than one name is shown, use the
- first one.
-
- To find it, try looking at the /etc/termcap... file (if you have it).
- If not, then either look at the terminfo trees (see `` Compiled
- database locations'') or try to find the terminfo source code file
- (see ``Source-code database locations''.
-
-
- 14.7. Rarely Needed /etc/ttytype File
-
- The configuration file /etc/ttytype is used to map /dev/ttySn's to
- terminal names per terminfo. tset uses it, but if the TERM
- environment variable is already set correctly, then this file is not
- needed. Since the Linux getty sets TERM for each tty, you don't need
- this file. In other Unix-like systems such as FreeBSD, the file
- /etc/ttys maps ttys to much more, such as the appropriate getty
- command, and the category of connection (such as "dialup"). An
- example line of Linux ttytype: vt220 ttyS1
-
-
- 14.8. Login Restrictions
-
- By default, the root user may not login from a terminal. To permit
- this you must create (or edit) the file /etc/securetty per the manual
- page "securetty". To restrict logins of certain users and/or certain
- terminals, etc. edit /etc/login.access (this replaces the old
- /etc/usertty file ??). /etc/login.def determines if /etc/securetty is
- to be used and could be edited so as to make /etc/securetty not needed
- (or not used). /etc/porttime restricts the times at which certain
- ttys and users may use the computer. If there are too many failed
- login attempt by a user, that user may be prohibited from ever logging
- in again. See the man page "faillog" for how to control this.
-
-
- 14.9. Run Command Only If TERM=my_term_type
-
- Sometimes there are commands that one wants to execute at start-up
- only for a certain type of terminal. To do this for the stty command
- is no problem since one uses the redirection operator < to specify
- which terminal the command is for. But what about shell aliases or
- functions? You may want to make a function for the ls command so it
- will color-code the listing of directories only on color terminals or
- consoles. For monochrome terminals you want the same function name
- (but a different function body) which will use symbols as a substitute
- for color-coding. Where to put such function definitions that are to
- be different for different terminals?
-
- You may put them inside an "if" statement in /etc/profile which runs
- at startup each time one logs on. The conditional "if" statement
- defines certain functions, etc. only if the terminal is of a specified
- type.
-
-
- 14.9.1. Example for ls Function
-
- While much of what this if statement does could be done in the
- configuration file for dircolors, here's an example for the case of
- the bash shell:
-
-
-
- ______________________________________________________________________
- if [ "$TERM" = linux ]; then
- eval `dircolors`;
- elif [ "$TERM" = vt220 ]; then
- ls () { command ls -F $* ; }# to export the function ls():
- declare -xf ls
- else echo "From /etc/profile: Unknown terminal type $TERM"
- fi
- ______________________________________________________________________
-
-
-
- 14.10. Character Mapping: mapchan
-
- There is a free program named "mapchan" which will map characters
- (bytes) typed at a terminal keyboard (input) into different characters
- per a user-supplied mapping table. It can also map characters which
- are sent to the screen (output). This is nice for remapping the
- keyboard for foreign language alphabets. Most distributions don't
- seem to supply it (let me know if any do). Source code by Yura
- Kalinichenko (Ukraine, but in Russian with English manual) was at
- "http://www.kron.vinnica.ua/free/download/" but this link is dead in
- 2003.
-
-
- 15. Terminfo and Termcap (detailed)
-
- 15.1. Intro to Terminfo
-
- Terminfo (formerly Termcap) is a database of terminal capabilities and
- more. For every (well almost) model of terminal it tells application
- programs what the terminal is capable of doing. It tells what escape
- sequences (or control characters) to send to the terminal in order to
- do things such as move the cursor to a new location, erase part of the
- screen, scroll the screen, change modes, change appearance (colors,
- brightness, blinking, underlining, reverse video etc.). After about
- 1980, many terminals supported over a hundred different commands (some
- of which take numeric parameters).
-
- One way in which terminfo gives the its information to an application
- program is via the "ncurses" functions that a programmer may put into
- a C program. For example, if a program wants to move the cursor to
- row 3, col 6 it simply calls: move(3,6). The move() function (part of
- ncurses) knows how to do this for your terminal (it has read
- terminfo). So it sends the appropriate escape sequence to the
- terminal to make this particular move for a certain terminal. Some
- programs get info directly from a terminfo files without using
- ncurses. Thus a Linux package that doesn't require ncurses may still
- need a terminfo file for your terminal.
-
- The terminfo abbreviations are usually longer than those of termcap
- and thus it's easier to guess what they mean. The manual pages for
- terminfo are more detailed (and include the old termcap
- abbreviations). Also, the termcap entries had a size limitation which
- is not present for terminfo. Thus, unless you are already committed
- to working with termcap, it's suggested you use terminfo.
-
-
- 15.2. Terminfo Database
-
- 15.2.1. Introduction
-
- The terminfo database is compiled and thus has a source part and a
- compiled part. The old termcap database has only a source part but
- this source can, by a single command, be both converted to terminfo
- source and then compiled. Thus you may get by without having any
- terminfo source since the termcap source can create the compiled
- terminfo database. To see a display of the database for the terminal
- you're now using (including a PC monitor) type "infocmp" and you
- should see the source terminfo "file" for it.
-
- To see if your terminal (say vt100) is in the terminfo data base type
- "locate vt100". If you need to find the terminfo name for your
- terminal, explore the listing of files in the compiled database or see
- ``What is the terminfo name of my terminal ?''
-
-
- 15.2.2. Where is the database located ?
-
- 15.2.2.1. Compiled database locations
-
- Typing "locate vt100" may show /usr/lib/terminfo/v/vt100,
- /usr/share/terminfo/v/vt100, /home/.../.terminfo/v/vt100, and/or
- /etc/terminfo/v/vt100. All these are possible locations of the
- compiled terminfo files. Although the /etc/terminfo directory is not
- a standard location for it, having a few terminal types there could be
- useful in case the /usr directory is not accessible. For example /usr
- could be on a separate disk or partition that failed to mount.
- Normally, programs that use your main terminfo data base are able to
- find it if it's in at least one of the locations mentioned above.
- Otherwise the environment variable TERMINFO may be set to the path to
- this database. Example: TERMINFO=/usr/share/terminfo
-
- For the Debian Distribution of Linux, several commonly used terminals
- (including the monitor-console) are in the ncurses-term package.
- These are put into /etc/terminfo/. All of the terminals in the
- database are in the ncurses-bin package and go into
- /usr/share/terminfo/.
-
- If the compiled terminfo is in more than one location, everything is
- usually OK until someone installs new terminfo files (from a newer
- distribution, from the net, by editing the old one, etc.). Each new
- terminfo file needs replace all the existing older copies of that file
- (at various locations) unless you abolish redundant locations. If you
- don't ensure this gets done, then some application programs could wind
- up still finding and using the old (and possibly buggy) terminfo data
- that sill exists in a "possible" location. Setting the environment
- variable TERMINFO to the up-to-date location (as mentioned above)
- would help avoid this problem.
-
-
- 15.2.2.2. Source-code database locations
-
- While the source-code file may not be installed on your computer
- there's another way to get the source-code if you have the compiled
- code. Just use the "infocmp" command.
-
- The source code file (for all terminals) may be /etc/termcap and/or
- terminfo.src (or another name). See the man pages: terminfo(5) or
- termcap(5) for the format required to create (or modify) these source
- files. The file terminfo.src may be in various locations on your
- computer or it may not be included with your Linux distribution. Use
- the locate command to try to find it. It is available on the web at
- .
-
-
- 15.2.3. Terminfo Compiler (tic)
-
- The data in the source files is compiled with the "tic" program which
- is capable of converting between termcap format and terminfo format.
- Thus you can create a compiled terminfo data base from termcap source.
- The installation program which was used to install Linux probably
- installed the compiled files on your hard disk so you don't need to
- compile anything unless you modify /etc/termcap (or terminfo.src ).
- "tic" will automatically install the resulting compiled files into a
- terminfo directory ready to be used by application programs. Which
- location it's installed in depends on ... See "man tic" for the
- explanation.
-
-
- 15.2.4. Look at Your Terminfo
-
- It's a good idea to take a look at the terminfo entry for the terminal
- you are using (source code of course) and read the comments. A quick
- way to inspect it without comments is to just type "infocmp". But the
- comments may tell you something special about the terminal such as how
- you need to set it up so that it will work correctly with the terminfo
- database.
-
-
- 15.2.5. Deleting Data Not Needed
-
- In order to save disk space, one may delete all of the terminfo
- database except for the terminals types that you have (or might need
- in the future). Don't delete any of the termcaps for a "Linux
- terminal" (the console) or the xterm ones if you use X Window. The
- terminal type "dumb" may be needed when an application program can't
- figure out what type of terminal you are using. It would save disk
- space if install programs only installed the terminfo for the
- terminals that you have and if you could get a termcap for a newly
- installed terminal over the Internet in a few seconds.
-
-
- 15.3. Bugs in Existing Terminfo Files (and Hardware)
-
- Unfortunately, there are a number of bugs in the terminfo and termcap
- files. In addition, many of these terminfo files are incomplete and
- do not define certain features available on the terminals. Sometimes
- you can get by without modifying the terminfo but in other cases you
- need to modify it or possibly use another emulation that has a good
- terminfo.
-
- The sad state of the supplied terminfo files is due to a number of
- reasons. One is that during the 1980's when many of them were written
- (often in termcap format), application programs did not utilize more
- advanced terminal features. Thus if such feature were not in the
- termcap (or terminfo) file, no one complained. Today, programs such
- as vim use "context highlighting" and minicom uses the terminal's
- graphics character set. These often need more definitions to be added
- to the old termcap. This may (or may not) have already been done.
-
- Most terminals had hardware bugs (in their firmware) and sometimes
- these were "fixed" by modifying the termcap. Then the manufacturer
- might send out replacement chips which would fix the bug. Not all
- owners would bother to get the replacement chips. Thus there may be 2
- or more terminfos for your terminal, depending on what firmware chips
- it has in it. This situation was often not noted in the termcap and
- only one termcap may be supplied with Linux. Some hardware bugs which
- existed for features that were almost never used in the past likely
- never did get fixed. Also, some reported hardware bugs may never have
- been fixed since they were not of much significance at the time or
- because the company went out of business, etc.
-
-
-
- 15.4. Modifying Terminfo Files
-
- To do this you need a manual for your terminal showing what escape
- sequences it uses. Newer manuals from the 1990's often don't show
- this. You also need a terminfo manual (the man page "terminfo" is
- one). After you edit the terminfo source file you compile it using
- "tic". "tic" should automatically put the compiled terminfo file in
- the correct directory reserved for it.
-
- If you would like to find a better terminfo entry for a certain
- terminal than the one supplied, you might try searching the Internet
- (but what you find could be worse). If your new terminfo entry is
- better than the old one and it seems stable (you've used it for a
- while with no problems) then you should send a copy to the maintainer
- of terminfo as noted at the start of the source file for terminfo (or
- termcap).
-
-
- 15.5. Init String
-
- Included in the terminfo are often a couple of initialization strings
- which may be sent to the terminal to initialize it. This may change
- the appearance of the screen, change what mode the terminal is in,
- and/or make the terminal emulate another terminal. No initialization
- string is automatically sent to the terminal to initialize it. One
- might expect that the getty program should do this. If it did, one
- could make a change to the set-up stored inside the terminal but this
- change wouldn't happen because the init string would override it.
- Application programs don't seem to initialize (send an init string per
- terminfo) either.
-
- To actually send an init string you must use a command given on the
- command line (or in a shell script such as /etc/profile). Such
- commands are: "tset", "tput init", or "setterm -initialize".
- Sometimes there is no need to send an init string since the terminal
- may set itself up correctly when it is powered on (using
- options/preferences one has set up and saved in the non-volatile
- memory of the terminal).
-
-
- 15.6. TERM Variable
-
- The Environment variable TERM should be set to the name of terminal
- which you are using. If TERM hasn't been set yet and you don't know
- the name of your terminal see ``What is the terminfo name of my
- terminal ?''. It is normally set by the terminal_type parameter
- passed to the getty program (look at it in the /etc/inittab file).
- This name must be in the Terminfo data base. Just type "set" at the
- command line to see what TERM is set to (or type: tset -q). At a
- console (monitor) TERM is set to "linux" which is the PC monitor
- emulating a fictitious terminal model named "linux". Since "linux" is
- close to a vt100 terminal and many text terminals are also, the
- "linux" designation will sometimes work as a temporary expedient with
- a text terminal.
-
- If more than one type of terminal may be connected to the same port
- (/dev/tty...) (for example, if there is a switch to permit different
- terminal types to use the same serial port, or if the port is
- connected to a modem to which people call in from different types of
- terminals) then TERM needs to be set each time someone connects to the
- serial port. There is often a query escape sequence so that the
- computer may ask the terminal what type it is. Another way is to ask
- the user to type in (or select) the type of terminal s/he is using.
- You may need to use tset for this or write a short shell script to
- handle this.
-
- One way to do this is to use "tset" (see the manual page). tset tries
- to determine the terminal name of the terminal you are using. Then it
- looks up the data in terminfo and sends your terminal an init string.
- It can also set the value of TERM. For example, a user dials in and
- logs in. The .profile login script is executed which contains within
- it the following statement: eval `tset -s ?vt100`. This results in:
- The user is asked if s/he is using a vt100. The user either responds
- yes or types in the actual terminal type s/he is using. Then tset
- sends the init string and sets TERM to this terminal name (type).
-
-
- 15.7. Terminfo/Termcap Documents
-
-
-
- · manual pages for terminfo(5) (best) and/or termcap(5). The Termcap
- Manual
- (2nd ed.) by Richard M. Stallman is a GNU manual which is somewhat
- obsolete since it doesn't include terminfo.
-
- · the files: terminfo.src and /etc/termcap have info about various
- versions of termcap files, naming conventions for terminals, and
- special capabilities code named u6-u9. If you don't have one, go to
-
-
- · "Termcap and Terminfo" is a book published by O'Reilly in 1988.
-
-
- 16. Using the Terminal
-
- 16.1. Intro to Using the Terminal
-
- This section is about controlling the terminal-computer interface
- and/or changing the terminal set-up while using the terminal. It
- explains (or points to explanations of) how the user of a terminal can
- control and inspect the interface and how to use various commands
- provided by the device driver. It does not explain how to use the
- many application programs, shells or most Linux utilities. Two
- commands commonly used at the terminal are:
-
-
- · clear (to clear the screen)
-
- · reset (to reset the terminal
-
- · setterm -reset (alternative for "reset" in case of bug)
-
-
- 16.2. Starting Up the Terminal
-
- Of course the power must be on for the terminal to work. If you don't
- see a login prompt hit the "return" (or "enter") key a few times.
- Then type your account name (followed by a return/enter) and your
- password when prompted for it (also followed by return/enter). Make
- sure not to type all capital letters. If you do, the computer may
- think that you have an old terminal that can't send lowercase letters
- and the serial driver may set itself up to send only capital letters
- to the terminal.
-
- If nothing happens, make sure that both the host computer and the
- terminal are OK. If the host computer is shut down (no power) what
- you type at the terminal keyboard may appear on the screen since the
- transmit and receive pins at the computer may be connected together
- resulting in echoing of characters by an "off" computer. If you can't
- log in when the host computer is running, see ``Trouble-Shooting''.
-
- 16.3. Terminal (Serial) Device Driver
-
- When typing at the command line, the shell (such as the Bash shell) is
- reading what you type and reacting to it. What you type first passes
- thru the terminal driver part of your operating system. This driver
- may translate certain characters (such as changing the "return"
- character generated by the "return" key into a "new-line" character
- for Linux files). It also recognizes certain control codes which you
- may type at the keyboard such as ^C to interrupt the execution of a
- program. It also normally echoes what you type back to the display.
- ``Stty'' may be used to configure how this terminal driver behaves,
- including disabling some (or all) of its functionality.
-
-
- 16.4. Problems with Editors
-
- There may be some problems with using both emacs and vi on some
- terminals. A few terminals have no escape key (ESC) so you may need
- to type Ctrl-[ to get ESC.
-
-
- 16.4.1. emacs
-
- If software flow control exists, then the ^S command in emacs will
- freeze the display. The ^Q command will unfreeze the display. One
- fix is to map this to another key-press by configuring emacs that way.
- Some terminals have meta keys although you may need to setup the
- terminal to create a meta key.
-
-
- 16.4.2. vi and Cursor-Keys
-
- Vi uses the esc-key as a command to exit insert mode. Unfortunately
- for most terminals the arrow-keys send an an escape sequence (starting
- with the ESC character) to the host. Vi must distinguish between
- these two meanings of ESC. A smart vi (such as vim if configured for
- it) is able to detect the difference by noting the time between the
- ESC and the next key. If it's a short time, then it's likely that a
- cursor key was pressed. Use "help cursor-keys" in vim to find out
- more.
-
- Here's another way to fix this. On VT terminals the left-arrow-key
- may be either set to send ESC [ D or ESC O D. The other arrow keys
- are similar but use A, B, and C instead of D. If you're having
- problems, choose ESC [ D since the "O" in the other alternative could
- be interpreted by vi as a command to "Open a line". The "[" should be
- interpreted by vi to mean that an arrow-key has been pressed. ESC [ D
- will be sent provided "Cursor Key Application Mode" has not been set.
- ESC [ D is normally the default so everything is seemingly OK. Except
- that many termcaps contain a string (not the init string) which sets
- what you want to avoid: "Application Mode". Editors may send this
- string to the terminal when the editor starts up. Now you are in
- trouble.
-
- This string has the termcap code "ks" (smkx in terminfo) meaning
- enable the function (and related) keys (including the arrow keys). An
- application enables these keys by sending the "ks" string to the
- terminal. Whoever wrote the termcap reasoned that if an application
- wants to enable these keys, then they should be put into "Application
- Key Mode" since this is an "application", but you don't want this.
-
- The Linux console has no "ks" string so you can't fall into this trap
- at the console. For other terminals you may need to edit the termcap
- (or terminfo) or use another termcap entry. You need to change not
- only the "ks" string but also the termcap definitions of what they
- send: kd, kl, kr, ku. Then run tic to install it.
- For vim (vi iMproved) there is a way to set it up to work OK with ESC
- O D (so you don't need to edit termcap): See vim help for
- "vt100-cursor-keys". You may run "gitkeys" and then press your cursor
- keys to see what they send but they may be set to send something
- different when you're in an editor.
-
-
- 16.5. Bugs in Bash
-
- There have been problems with the readline interface to the Bash
- shell. Bash 2.01 (1998) had a readline interface which was quite
- corrupted if one used a dumb terminal. This was fixed in later
- versions. One problem still outstanding is that if certain terminal
- keys send bytes with the high order bit set to 1, then Bash seems to
- ignore the meaning for them as defined in a terminfo entry. I've
- reported this as a bug in Bash. Other programs such as the vim editor
- and the lynx browser work OK with such keys.
-
- To work around this problem one may define what these keys should do
- in Bash by putting such definitions into /etc/inputrc. For example, A
- Wyse 60 will send D0-D3 when the arrow-keys are hit provided the
- terminal is in "application key mode". After modifying the terminfo
- to reflect this, they still wouldn't work on the command line in the
- Bash shell. So I explicitly defined the arrow-keys in /etc/inputrc
- like this:
-
-
-
- # Arrow keys in 8 bit keypad mode: Sends d0-d4. -ap means application.
- $if term=wy60-25-ap
- set enable-keypad on
- "\xd0": backward-char
- "\xd1": forward-char
- "\xd2": next-history
- "\xd3": previous-history
- $endif
-
-
-
- If the terminal is already in "application key mode" there's no need
- to "set enable-keypad on". enable-keypad will send the terminal the
- escape sequence named smkx in terminfo (which for wyse60 is \E~3 and
- makes the arrow keys send D1-D3). Many other application send this
- without needing to be told to do so.
-
-
- 16.6. Color ls Corruption
-
- If ls is corrupting your terminal emulation with the color feature,
- turn it off. ls --color, and ls --colour all use the color feature.
- Some installations have ls set to use color by default. Check
- /etc/profile, etc. for ls aliases. See ``Example for ls Function''
- for how to have ls do color for the console and do monochrome for
- terminals.
-
-
- 16.7. Display Freezes (hung terminal)
-
- The symptom of a hung terminal is where what you type doesn't display
- on the terminal (or in some cases displays but doesn't do anything).
- If what you type is invisible (or does nothing) type ^Q to restart
- flow (if flow control stopped it). Hanging may also be due to:
- ``Sent terminal binary'' or ``Abnormally exited a program''
- If you didn't do any of these two, then the program you're running
- could by buggy or you interaction with it fatally illegal.
- If you want to quit the program you were running and you can't do it
- by the usual methods (some programs have special keys you must hit to
- exit) then try killing it from another terminal using "top" or "kill".
- If the process refuses to die, then kill it with signal 9 from top (or
- use "kill" on the command line). The "9" type of forced exit may leave
- some temporary files lying around as well as a corrupted interface.
- If this doesn't work, killing the login shell should result in a
- startup of getty with a new login prompt. If all else fails, you may
- need to reboot the computer or even power it down. Just rebooting may
- not alter the possibly corrupted content of the serial port hardware
- registers.
-
-
- People new to Linux may unintentionally press Ctrl-S (^S) (or the "No
- Scroll" key) which mysteriously freezes the screen (although that is
- what this key is supposed to do if you use software flow-control). To
- restore normal screen interaction, press Ctrl-Q (^Q). Note that
- everything typed during the "freeze" gets executed but you don't see
- any report of this until you hit ^Q. Thus when it's frozen, don't
- type anything drastic that might destroy files, etc. One argument for
- using hardware flow-control is to prevent such freezes.
-
-
- 16.8. Corrupted Terminal Interface
-
- This includes the case of a "frozen display" = "hung terminal" of the
- previous section.
-
-
- 16.8.1. Symptoms and some fixes
-
- When the display doesn't look right, or when what you type doesn't
- display correctly (if at all), or nothing happens when you type a
- command, you may have a corrupted terminal interface. In rare cases,
- when the serial port hardware gets itself corrupted, the only fix may
- be to cycle power (turn off the PC and reboot). In some cases just
- cycling power for the terminal will fix it. Sometimes logging in
- again will solve the problem. To do this, kill the shell process
- running on the terminal (or kill getty if it's running). You may do
- this from another terminal. Once killed, a new getty process respawns
- which hopefully will end the corruption. Recycling power (or
- resetting) for the terminal may help too.
-
- The corruption may be due to things such as:
-
- · A bug in the program you're using (including a program which
- erroneously assumes that you are using a terminal of type "linux")
-
- · A hardware failure (including an obscure hardware defect that you
- can normally live with)
-
- · Incorrect configuration (including an error in the terminfo or the
- terminal type)
-
- If everything was working normally but it suddenly goes bad, it may
- be that the interface got corrupted by something you did. Three
- mistakes you might have made to corrupt the interface are:
-
-
- · ``Sent terminal binary''
-
- · ``Abnormally exited a program''
-
- · ``Typed ctrl-S by mistake''
-
-
- 16.8.2. Sent terminal binary characters
-
- Your terminal will change its characteristics if sent certain escape
- sequences or control characters. It you inadvertently try to display
- a binary file, it might by chance contain such sequences which may put
- your terminal into some strange mode of operation or even make it
- unusable. Always view or edit a binary file with programs designed
- for that purpose so that this doesn't happen. Most editors and pagers
- will handle binary OK so as not to corrupt the interface. Some may
- display a message telling you that they can't edit binary. But you're
- likely to corrupt things if you: "cat ...." or "cp .... /dev/tty.." or
- run a program which sends binary output to "standard output" (unless
- you redirect such output with >, etc.).
-
- Corruption can also happen when using a communications program where a
- remote computer may send binary to your screen. There are numerous
- other ways it can happen so be prepared for it. Even a supposedly
- text file could contain unwanted control codes.
-
- To fix this problem reset the terminal. Type either just "reset" (may
- be broken) or "setterm -reset" (followed by a of course).
- You may not be able to see what you're typing. This will send the
- reset string from the terminfo entry to the terminal. As an
- alternative to this, if the correct set-up has been saved inside the
- terminal then pressing a special key(s) (perhaps in setup mode) may
- restore the settings. Then you might still need to use "tset" to send
- the init string if you use it to set up your terminal.
-
-
- 16.8.3. Reset command was broken but now fixed
-
- Note that in 2000 the "reset" command appeared to be broken for
- terminals that needed "clocal" set since "reset" seemed to unset
- "clocal". In 2001 it appears to be fixed so you may not need to read
- the rest of this paragraph. If you have this problem, using "reset"
- will only make the situation worse by disabling communication between
- the terminal and computer. You will likely need to log in again and
- hope the getty sets "clocal". If you see a login prompt without
- asking for it, you're in luck. Otherwise see ``Symptoms and some
- fixes'' for how to get a login prompt. You should try out "reset"
- before you need it and use "setterm -reset" if "reset" logs you out or
- otherwise doesn't work right. I submitted a bug report in Mar. 2000
- but never got a "fixed" notice.
-
-
- 16.8.4. Character corruption
-
- For the case where you see strange "graphic" characters instead of the
- normal ones, pressing ^O may switch back to the normal letters. The
- "reset" command also does this but it resets everything else too.
-
- There's the case where all letters have the wrong attribute (too dim,
- bright, blinking, or even invisible :-) but the whitespace created by
- tab characters is normal. This was caused by an escape sequence which
- set this attribute but the attribute doesn't apply to the whitespace
- created by tab characters. Fix by resetting, etc.
-
-
- 16.8.5. Abnormally exited a program
-
- Large application programs (such as editors) often use the stty
- command (or the like) in their code to temporarily change the stty
- configuration when you are running the program. This may put the
- device driver into "raw" mode so that every character you type goes
- directly thru to the application program. Echoing by the driver is
- disabled so that everything you see on the screen comes directly from
- the application program. Thus many control commands (such as ^C) may
- not work within such applications.
-
- When you tell such an application to quit, the application program
- first restores the stty settings to what they were before the
- application program started. If you abnormally exit the program then
- you may still be in "raw mode" on the command line. You should
- suspect this has happened when what you type no longer displays on the
- screen.
-
- To get out of raw mode and restore the normal stty settings type "stty
- sane". However, you must type this just after a "return" and end it
- with a "return". But hitting the "return" key doesn't do the job
- since the "return" code no longer gets translated to the new-line
- characters that the shell is waiting for. So just type new-line (^J)
- instead of "return". The "sane" terminal interface may not be exactly
- the same as the normal one but it usually works. "stty sane" may also
- be useful to get out of a corrupted interface due to other causes.
-
-
- 16.9. Special (Control) Characters
-
- A number of control characters which you may type at the keyboard are
- "caught" by the terminal driver and perform various tasks. To see
- these control commands type: stty -a and look at lines 2-4. They are
- tersely explained in the stty manual pages. They may be changed to
- different control characters or disabled using the stty command. Thus
- your control characters might be different than those described below.
- They are used for command-line editing, interrupting, scrolling, and
- to pass the next character thru transparently.
-
-
- 16.9.1. Command-Line Editing
-
- While the terminal driver has a few commands for command-line editing,
- some shells have a built-in real editor (such as "readline" in the
- Bash shell). Such an editor is normally on by default so you don't
- need to do anything to enable it. If it's available you don't need to
- learn many of the following commands although they often still work
- along with the command-line editor. The most important to learn are
- ^C (interrupt), ^D, and how to stop scrolling.
-
-
- · Delete-key (shown by stty as ^?) erases the last character
-
- · ^U kills (deletes) the line
-
- · ^W deletes a word backwards
-
- · ^R reprints the line. Useful mainly on hard copy terminals ??
-
-
- 16.9.2. Interrupting (& Quit, Suspend, EOF, Flush)
-
-
-
- · ^C interrupts. Exits the program and returns you to the command-
- line prompt.
-
- · ^\ quits. Same as interrupt. Also may dump a "core" file (which
- you likely have no use for) into your working directory.
-
- · ^Z suspends. Stops the program and puts it in the background.
- Type fg to restart it.
-
-
- · ^D end of file. If typed at the command-line prompt, exits the
- shell and goes to where you were before the shell started.
-
- · ^O flush (or discard). Not yet implemented in Linux (but
- proposed). Sends output to /dev/null.
-
- · ^T display driver status. Not yet implemented in Linux (but
- proposed). Displays a status line for the interface (number of
- bytes sent, etc.).
-
-
- 16.9.3. Stop/Start Scrolling
-
- If what you want to see scrolls off the bottom of the screen, you may
- prevent this by sending a "stop" signal (^S or Xoff) to the host
- (provided Xon-Xoff ``Flow Control'' is enabled). Send a "start signal
- to resume (^Q or Xon). Some terminals have a "No Scroll" key which
- will alternately send Xoff and Xon or possibly send the hardware flow
- control signals ?? Here's what ctrl-S (^S) and ctrl-Q (^Q) do:
-
-
- · ^S stops scrolling (Xoff)
-
- · ^Q resume scrolling (Xon)
-
- If you want to both stop scrolling and quit, use ^C. If you want to
- stop scrolling to do something else but want to keep the program that
- was generating the output in memory so you can resume scrolling later,
- use ^Z suspend.
-
- An alternative scrolling method is to pipe the output thru a pager
- such as more, less, or most. However, the output might not be
- standard output but could be error output which the pager doesn't
- recognize. To fix this you may need to use redirection "2>&1" to get
- the pager to work OK. It is often simpler to just use ^S and ^Q
- unless you need to scroll backwards.
-
- At a PC console (emulating a terminal) you may scroll backwards by
- using Shift-PageUp. This is frequently needed since the scrolling is
- often too fast to stop using ^S. Once you've scrolled backwards
- Shift-PageDown will scroll forward again.
-
-
- 16.9.4. Take next character literally
-
- ^V sends the next character typed (usually a control character)
- directly thru the device driver with no action or interpretation.
- Echoed back are two ASCII characters such as ^C.
-
-
- 16.10. Viewing Latin1 Files on a non-Latin1 terminal
-
- Some "text" files are 8-bit Latin1 (=ISO-8859-1). See ``Character-
- Sets''. If you have a terminal that will not display Latin1 (or don't
- have the Latin1 character set installed), then certain symbols (such
- as a bullet) will display wrong. When viewing manual pages (they are
- Latin1) you may give the option -7 to man so as to translate
- everything to ASCII. Are there some pagers that make these
- translations ??
-
-
- 16.11. Eliminating Overstriking in Files
-
- If one uses the "man" command to view a manual page but instead
- redirects the output to a file, that file will have overstrikes in it.
- Overstrikes are where some printed characters appear bold by printing
- them twice in the same location. Thus to print an overstrike
- character the file contains a backspace after the character and then
- the same character repeated. If this is in a file, it's fine if you
- are going to print it on a printer (unless the normal output from the
- printer is so darks that overstriking makes little improvement). But
- it's not so good if you want to use the file to email or edit.
-
- One way to get rid of the overstrikes is to use the "ul" (underline)
- command. You type: ul -t dumb my_overstruck_file > output_file The ul
- command converts overstrikes to bold for whatever terminal is
- specified and adds escape sequences to the output_file to generate the
- bold. But the terminal of type "dumb" has no escape sequences so you
- get the desired result. There are other ways to do this but this is a
- possible use for a terminal of type "dumb".
-
-
- 16.12. Inspecting the Interface
-
- These utility programs will provide information about the terminal
- interface:
-
- · gitkeys: shows what byte(s) each key sends to the host.
-
- · tty: shows what tty port you are connected to.
-
- · set: shows the value of TERM (the terminfo entry name)
-
- · stty -a: shows all stty settings.
-
- · setserial -g /dev/tty?? (you fill in ??) shows UART type, port
- address and IRQ number.
-
- · infocmp: shows the current terminfo entry (less comments)
-
-
- 16.13. Changing the Terminal Settings
-
- The terminal settings are normally set once when the terminal is
- installed using the setup procedures in the terminal manual. However,
- some settings may be changed when the terminal is in use. You
- normally would not give any "stty" of "setserial" commands when the
- terminal is in use as they are likely to corrupt the terminal
- interface. However, there are changes you may make to the appearance
- of the terminal screen or to its behavior without destroying the
- integrity of the interface. Sometimes these changes are made
- automatically by application programs so you may not need to deal with
- them.
-
- One direct method of making such changes is to use the setup key (or
- the like) at the terminal and then use menus (or the like) to make the
- changes. To do this you may need to be familiar with the terminal.
- The other 3 methods send an escape sequence from the computer to the
- terminal to make the changes. These 3 examples show different methods
- of doing this to set reverse video:
-
-
- 1. setterm -reverse
-
- 2. tput -rev
-
- 3. echo ^[[7m
-
-
-
- 16.13.1. setterm
-
- This is the easiest command to use. It uses long options (but doesn't
- use the normal -- before them). It consults the terminfo database to
- determine what code to send. You may change the color, brightness,
- linewrap, keyboard repeat, cursor appearance, etc.
-
-
- 16.13.2. tput
-
- The "tput" command is similar to "setterm" but instead of using
- ordinary words as arguments, you must use the abbreviations used by
- terminfo. Many of the abbreviations are quite terse and hard to
- remember.
-
-
- 16.13.3. echo
-
- In the example "echo ^[[7m" to set reverse video, the ^[ is the escape
- character. To type it type ^V^[ (or ^V followed by the escape key).
- To use this "echo" method you must find out what code to use from a
- terminal manual or from terminfo or termcap. It's simpler to use
- setterm or tput if you are typing on the command line. Since "echo
- ..." will execute faster (since it doesn't do any lookups) it's good
- for using in shell scripts which run at start-up, etc.
-
-
- 16.13.4. Saving changes
-
- When you turn off the terminal the changes you made will be lost
- (unless you saved them in non-volatile terminal memory by going into
- set-up mode and saving it). If you want to use them again without
- having to retype them, put the commands in a shell script or make it a
- shell function. Then run it when you want to make the changes. One
- way to make the changes semi-permanent is to put the commands in a
- file that runs each time you login or start up the computer.
-
-
- 16.14. Multiple Sessions
-
- The "screen" package runs multiple sessions something like virtual
- terminals on the console: See ``The Console: /dev/tty?''. You can
- switch back and forth between the sessions. The non-free Facet Term
- software also does this. See FacetTerm
-
-
-
- 16.15. Logging Out
-
- To log out type either "logout" or "exit". Under some circumstances
- your request will be refused, but you should be told why. One reason
- for refusal is if you are not in the same shell that you logged into.
- Another way to log out is to press ^D. Since ^D is also used for
- other purposes, you may not want it to log you out. If you set
- IGNOREEOF in the Bash shell then ^D will no longer log you out.
-
-
- 16.16. Chatting between Terminals, Spying
-
- If two persons logged into terminals on the same host computer want to
- chat with each other they may use the "write" or the "talk" (better)
- program. One may prevent anyone (except the superuser) from writing
- (sending messages) to their terminal by using the "mesg" command.
-
- For spying on what someone else is doing at their terminal use the
- "ttysnoop" program. In "ttysnoop" the two terminals have the same
- status and anything typed on either keyboard appears on both screens
- (in the same location). So if you're really spying and don't want to
- be detected, you shouldn't type anything.
-
- "ttysnoop" can be used for training with instructor and trainee
- sitting side-by-side, each at their own terminal. The instructor may
- watch what the trainee is typing and can correct any mistakes by
- typing it correctly. The trainee can watch what the instructor types
- and then try typing it. It's just like they used one terminal with
- both people having their hands on the keyboard at the same time.
-
- There's one shortcoming to "ttysnoop" and that is that the terminals
- involved should all be (or emulate) the same type of terminal (such as
- vt100). Since the "Linux" emulation done by a console (monitor) and
- the "minicom" emulation are close to vt100 one may use ttysnoop using
- two PCs, one running "minicom" which emulates a terminal.
-
- There's a non-free program called "DoubleVision" that is something
- like ttysnoop but does much more. Terminals may be of different types
- and it can remember and playback sessions on terminals so you can
- observe what happened in the past. The webpage is at
- .
-
-
- 16.17. Sharing the Serial Port
-
- It's possible to use the same serial port for both a text-terminal and
- another serial device such as a printer or modem. Making the physical
- connection is easy using one of these methods:
-
- · Just unplug the terminal cable and plug in the other device
-
- · Use an AB switch to switch between the terminal and other device
- (uses 3 cables)
-
- · Use the printer (or aux) port on the terminal for the other device
-
- When you are not using the serial port for a terminal, then you need
- to make sure that no characters intended for the terminal are sent to
- the other device by mistake. One unsafe way to do this is to let the
- programs running on the terminal keep running, provided they don't
- send out anything for the terminal when you are using the other
- device. This sometimes works since a terminal running on a serial
- port doesn't prevent another program (process) from opening the same
- port. This sometimes works if the other device is a printer. But if
- the other device should send bytes to the serial port on the computer,
- then the program(s) for the terminal which are still running on the
- port will often send back some bytes for the terminal which will
- actually go to the other device as garbage.
-
- To avoid this, it's best to kill all programs (processes) running on
- the terminal before using the other device. This is not quite as easy
- as it sounds. You normally have a shell (such as Bash) running on the
- port and if you kill Bash (by logging out for example) then the
- program "getty" will start up on the port to try to log you in again.
- If you kill getty, it will respawn and start up again. So at first
- glance it seems impossible to kill all processes on the terminal's
- serial port.
-
- One way to work around this problem is to switch runlevels so that no
- getty program or shell is running on the port. For the runlevel fix,
- you may create another runlevel in which no getty program runs on the
- port. Then you enter this new runlevel and use the serial port for
- something else. To set this up you need to edit /etc/inittab and
- check and/or set the runlevels at which getty runs. For example the
- line: "S1:23:respawn:/sbin/getty ..." means that getty will run (on
- ttyS1) in runlevels 2 and 3. Now you could have it only run in level
- 2 (by deleting "3") and then go to runlevel 3 when you want to use the
- other serial device. Thus to use the serial port for something else,
- the super-user would type "init 3" to switch to runlevel 3. Type
- "init 2" to get back to runlevel 2. Note that each runlevel may have
- a different set of initialization scripts but you can change this if
- you want, so that the same scripts are run in both runlevels. How the
- scripts and runlevels work are distribution dependent. For the Debian
- distribution, the explanation of this is in /usr/doc/sysvinit, but
- also look in /usr/share/doc.
-
- There's also the problem of the stty configuration of the port. When
- the port is being used for the terminal it has certain configurations
- but when say "init 3" is used to switch runlevels and disable getty on
- the port, the original (boot-time) configuration of the port is not
- restored. You are likely to wind up with the port configured in a
- "raw" mode. This means that the serial port likely needs to be fully
- reconfigured by stty, either by a script you write or by the next
- application which runs on the port. Some applications such as
- printing from the serial port may not capable of fully reconfiguring.
- The obsolete version of /etc/printcap could only partially reconfigure
- (but the new one under "lprng" can). Thus you might need to write a
- script to do it. The stty configuration of a terminal will be
- different depending on whether a shell is running on it, whether it's
- at the "login" prompt, etc. Thus the stty configuration after
- switching runlevels may vary.
-
-
- 16.18. Browsers for Terminals
-
- The "lynx" browser works correctly with all text terminals. There are
- two other text browsers: "w3m" and "links" that only work with the
- Linux console, xterm, or vt100 terminals. The "netrik" browser
- requires a color terminal. For "links", you must set your terminal to
- 8-bits with no parity. All (including netrik ??) support ssl (secure
- socket layer) for encoded communication.
-
- "w3m" and "links" overcome some of the "lynx" deficiencies. They can
- usually display tables better and can display frames side-by-side.
- Unfortunately, the width of what they try to display (for tables and
- frames) is often wider than the terminal width so the text may run
- off the right side of the screen. This requires scrolling sideways to
- see everything. Doing this may cause the names of the table rows to
- disappear from the screen. So in some cases, using "lynx" may be
- better.
-
- Unfortunately "w3m" and "links" don't have numbered links like lynx
- does, nor do they have good support for cookies. None of the text
- browsers as yet have good support for Javascript, but some are
- allegedly working on it (as of 2003). Links and netrik currently have
- only partial support for Javascript.
-
- There are still other text browser projects. Some of them seem to be
- dead.
-
-
- 17. Special Uses for a Terminal
-
- 17.1. Make a Serial Terminal the Console
-
- This will turn a text-terminal (or emulator PC) into a "serial
- console". Many messages from the system are normally only sent to the
- console (the PC monitor). Some of the messages sent to the console at
- boot-time may also be seen on any terminal after the boot succeeds by
- typing the command: dmesg. If the boot failed this will not be of any
- use since the terminal can't work without an operating system. It's
- possible to modify the Linux kernel so as to make a terminal serve as
- the console and receive all the messages from Linux intended for the
- console. Unfortunately, the messages from the BIOS (which display on
- the monitor when a PC is first started) will not display on this
- terminal (but still display on the monitor).
-
- There's a Remote-Serial-Console-HOWTO on this topic. Some people use
- a serial console when they run a PC without a monitor or keyboard.
- Normally, a PC will not start up without a keyboard and video card but
- some BIOSs permit it. If you are lucky enough to have such a BIOS
- that supports "console re-direct" you will likely then need to setup
- the BIOS using the CMOS menus when you start your PC.
-
- The method of creating a "serial console" depends on your kernel
- version. In any case serial support needs to be compiled into the
- kernel and not supplied as a module.
-
-
- 17.1.1. For Kernels 2.2 or higher
-
- The instructions for creating a serial-console are included with the
- kernel documentation in: Documentation/serial-console.txt. Kernel
- 2.4+ has better documentation and mentions the need to run getty on
- the serial port. Normally, the device /dev/console is linked to tty0
- (the PC console). For a serial-console you create a new /dev/console
- by
-
-
- mknod -m 622 console c 5 1
-
-
-
- You must also put statements regarding the serial-console into
- /etc/lilo.conf and then run lilo. This is because the equivalent of
- "setserial" needs to be run early before the kernel is loaded so that
- the serial-console can display the booting. See the above mentioned
- kernel documentation and the man page for lilo.conf for more details.
-
- Here is an example /etc/lilo.conf file contents (for ttyS0):
-
-
- prompt
- timeout=50
- boot = /dev/sda
- vga = normal # force sane state
- install = /boot/boot.b
- message = /boot/message
- image = /vmlinuz
- root = /dev/sda1
- label = console
- serial = 0,9600n8
- append = "console=ttyS0"
-
-
-
- The same PC may have more than one serial console but the last console
- mentioned in the "append" statement becomes the main console that you
- interact with ?? See the kernel docs (but it's not too clear).
-
-
- 17.1.2. For Kernels before 2.2
-
- The Linux Journal in April 1997 had an article on patching the Linux
- kernel. You add a couple of #defines at the start of
- src/linux/drivers/char/console.c:
-
-
-
- #define CONFIG_SERIAL_ECHO
- #define SERIAL_ECHO_PORT 0x2f8 /* Serial port address */
-
- The following was not in the Linux Journal article.
- In kernel 2.+ (and earlier ??) you need to also set the baud
- rate (unless 9600 is OK). Find these 2 lines:
-
- serial_echo_outb(0x00, UART_DLM); /* 9600 baud */
- serial_echo_outb(0x0c, UART_DLL);
-
- Change 0x0c in the line above (depending on the baud rate you want):
-
- 115200 baud: 0x01 19200 baud: 0x06 2400 baud: 0x30
- 57600 baud: 0x02 9600 baud: 0x0c 1200 baud: 0x60
- 38400 baud: 0x03 4800 baud: 0x18
-
-
-
- If you currently use the console to select which operating system to
- boot (using LILO), but would like to do this from a terminal, then you
- need to add a line to the /etc/lilo.conf file. See the manual page
- for lilo.conf and search for "serial=".
-
-
- 17.2. Run Linux without a Monitor
-
- One way to do this is to just use a terminal (serial console) for the
- monitor See ``Make a Serial Terminal the Console''. You may still
- need a video card since many BIOSs require one to get the PC started.
- Your BIOS may also require a keyboard to get started or it may have an
- option where you can set the BIOS not to require a keyboard.
-
- If you boot without a monitor, make sure that the boot loader (such as
- LILO or GRUB) doesn't try to present any image on the screen. A text-
- terminal can't display it and the booting may hang.
-
- If you have a keyboardless terminal, it can also be used as a monitor
- by use of the ttysnoop program. As of yet, it doesn't work like a
- console since it doesn't get all the initial boot-time messages. See
- ``Use a Keyboardless Terminal as the Monitor''
-
-
- 17.3. Use a Keyboardless Terminal as the Monitor
-
- 17.3.1. How it works
-
- While you might think that a terminal without a keyboard is useless it
- is possible to use it as the monitor and type on the PC's own
- keyboard. This may be done by using the spy program ttysnoop. This
- program permits a person at one terminal to spy on (or snoop) what
- someone else is typing at another terminal (or the PC console-
- monitor).
-
- Now suppose you are typing away at the monitor tty1. Imagine that
- someone with a terminal on ttyS2 is spying on you (with ttysnoop) and
- has a screen that looks just like your screen. Everything you type at
- tty1 also displays on ttyS2. Now move the spy terminal (on ttyS2) so
- it is side-by-side with your monitor (on tty1). Everything you type
- on the PC keyboard will now display on the two screens in front of
- you: the monitor and the spy terminal. Now just look only at the spy
- terminal as you type. Disconnect both the monitor and the terminal
- keyboard since you're not using either. Thus you are now using a
- keyboardless terminal as a monitor. What a simple but clever
- solution!
-
- One possible problem (which turns out to be no problem at all) is that
- normally, the type of spy terminal should be the same as the type of
- terminal being spied upon. Since the monitor is normally declared as
- a terminal of type "linux" (which is close to vt100), you might think
- that the real terminal should also be (or at least emulate) a vt100.
- Not necessarily so! For example, if you have a wyse60 terminal you
- simply falsely declare that you have a wyse terminal on tty1 (tell the
- getty program for tty1 that it's a wyse60).
-
- Here's why you can get away with this. Go back the the scenario where
- you have both the monitor and the wyse60 terminal in front of you,
- both displaying the same thing (or trying to). Ttysnoop will be
- sending the wyse60 the same bytes as are going to the monitor. If
- you've falsely claimed that the monitor is a wyse60, then you'll have
- wyse60 escape sequences going to both the monitor and the wyse60
- terminal (via ttysnoops). The display on the wyse60 is fine but the
- display on the monitor is corrupted since it's getting wyse60 escape
- sequences. Since you will not use the monitor (and are about to
- disconnect it) this corruption is never a problem (you simply don't
- see it).
-
-
- 17.3.2. Example configuration
-
- This is not the ideal setup since ttysnoop runs so late that the login
- prompt doesn't appear. This example is for a wyse60 terminal on ttyS2
- and the missing monitor/PC-keyboard on tty1. It uses the agetty
- program for getty as supplied by the Debian distribution. Your getty
- may require a different format.
-
- In /etc/inittab:
-
-
- 1:2345:respawn:/sbin/getty 38400 tty1 wyse60 -ln /usr/sbin/ttysnoops
-
-
-
- Note that ttysnoop/ttysnoops is a client-server combo so the "s" is
- not a typo. If you don't use -n you may not see a login prompt on the
- terminal. With no -n, agetty issues the prompt before the ttysnoop is
- activated. With -n, agetty doesn't issue the prompt (but login does
- instead). If you use -n, agetty will no longer automatically detect
- parity but if you don't use parity all is OK.
-
- In /etc/snooptab:
-
-
- # tty snoopdev type execpgm
- tty1 /dev/ttyS3 init /usr/local/bin/sterm
-
-
-
- In the above, a script named sterm is used to run the stty program.
- You may not need this or may want to use it for another purpose.
- Here's the example sterm script in /usr/local/bin/sterm:
-
-
-
- #!/bin/sh
- stty rows 24
- /bin/login $@
-
-
-
- 18. Trouble-Shooting
-
- If you suspect that the problem is a hardware problem, see the
- ``Repair and Diagnose'' section. If it's the keyboard see
- ``Keyboards''. If it responds incorrectly (if at all) to what you
- type. see ``Corrupted Terminal Interface''. If the problem involves
- the serial port itself see the Serial-HOWTO.
-
- Here is a list of possible problems:
-
- · ``Is the Terminal OK ?'' Suspect the terminal is defective.
-
- · ``Display Freezes (hung terminal)''
-
- · ``Displays Foreign/Weird Characters/Symbols''
-
- · ``Displays Escape Sequences''
-
- · ``Missing Text'' Either skips over some text or displays some text
- OK and hangs.
-
- · ``All Keys Work Erratically; Must Hit a Key a Few Times''
-
- · ``If getty run from command line: Programs get stopped'' with
- message "Stopped"
-
- · ``Getty Respawning Too Rapidly'' (console error message)
-
- · ``Fails Just After Login''
-
- · ``Can't Login'' but login prompt is OK.
-
- · ``Garbled Login Prompt''
-
- · ``No Login Prompt''
-
- There are two cases where the terminal goes bad. One is when it's
- been recently working OK and suddenly goes bad. This is discussed in
- the next sub-section. The other case is where things don't work right
- just after you install a terminal. For this case you may skip over
- the next section.
-
-
- 18.1. Terminal Was Working OK
-
- When a formerly working terminal suddenly goes bad it is often easy to
- find the problem. That's because (except for hardware failures) the
- problem is likely due to something that you did (or something the
- software that you used did).
-
- The problem may be obvious such as an error message when the terminal
- is first turned on. If it makes a strange noise it likely needs
- repair. See ``Repair & Diagnose''. First, think about what has been
- done or changed recently as it's likely the cause of the problem. Did
- the problem happen just after new system software was installed or
- after a change in the configuration?
-
-
- If the terminal isn't responding correctly (if at all) to what you
- type to it, you may have a ``Corrupted Terminal Interface''.
-
-
- 18.2. Terminal Newly Installed
-
- If you've just connected up a terminal to a computer per instructions
- and it doesn't work this section is for you. If a terminal that
- formerly worked OK doesn't work now then see ``Terminal Was Working
- OK'' If you suspect that the serial port on your computer may be
- defective you might try running a diagnostic test program on it. At
- present (June 1998) it seems that Linux doesn't yet have such a
- diagnostic program so you may need to run diagnostics under MS
- DOS/Windows. There are some programs to monitor the various serial
- lines such at DTR, CTS, etc. and this may help. See ``Serial
- Monitoring/Diagnostics''
-
- One approach is to first see if the the terminal will work by trying
- to copy a file to the terminal (cp my_file /dev/ttyS?) under the most
- simple situation. This means with the modem control lines disabled
- and at a show speed that doesn't need flow control (make sure that any
- hardware flow control is disabled). If this copy works, then make the
- situation a little more complicated and see if it still works, etc.,
- etc. When the trouble appears just after you made a change, then that
- change is likely the source of the trouble. Actually, its more
- efficient (but more complex) to jump from the simple situation to
- about half way to the final configuration so that the test eliminates
- about half of the remaining possible causes of the problem. Then
- repeat this methodology for the next test. This way it would only
- take about 10 tests to find the cause out of a thousand possible
- causes. You should deviate a little from this method based on hunches
- and clues.
-
-
- 18.3. Is the Terminal OK ?
-
- Many terminals will start up with some words on the screen. If these
- words convey no error message, it's probably OK. If there is no sign
- of power (a dark screen, etc.) re-plug in the computer power cord at
- both ends. Make sure there is power at the wall jack (or at the
- extension cord end). Try another power cord if you have one. Make
- sure the terminal is turned on and that its fuse is not blown. A
- blank (or dim) screen may sometimes be fixed by just turning up the
- brightness and contrast using knobs or a keyboard key in set-up mode.
-
- A terminal that's been stored for a long time may take a while to
- "warm up" as the electrolytic capacitors heal themselves under
- voltage. If it still won't work See ``Repair & Diagnose'' for tips on
- repairing it.
-
- If the terminal starts up OK, but you suspect that something may be
- wrong with it, go into "local mode" where is works like a typewriter
- and try typing on it. See ``Local Mode''. Before you have trouble,
- you should find out if your terminal displays error messages if the
- hardware is bad. One way to test a terminal for this is to turn it on
- with the keyboard unplugged and see if it displays an error message.
-
-
- 18.4. Missing Text
-
- If several lines or text displays on the terminal OK and then it stops
- without finishing (in the middle of a word, etc.) or if big chunks of
- text are missing, you likely have a problem with flow control. If you
- can't figure out right away what's causing it, decrease the speed. If
- that fixes it, it's likely a flow control problem. It may be that
- flow control is not working at all due to failure to configure it
- correctly, or due to incorrect cable wiring (for hardware flow
- control). See ``Flow Control''
-
- If you can type OK at the terminal but when text is sent to the
- terminal, only about 1 in every 16 characters sent gets thru, then you
- may have given the wrong UART to setserial. This will happen if the
- port is an obsolete 16550 (or lower) but you've told setserial it's a
- 16550A or higher.
-
- If single characters are missing, perhaps the serial port is being
- overrun by too fast a speed. Try a slower baud rate.
-
- If your device is under 1200 baud (probably a very slow old hard-copy
- terminal or printer) and the text gets truncated, then the problem may
- be in the serial device driver. See Printing-HOWTO under "Serial
- devices" on how to fix this.
-
-
- 18.5. All Keys Work Erratically; Must Hit a Key a Few Times
-
- This is where you need to hit a key a few times before it works (and
- see the letter you typed on the screen). If you type a word, some (or
- even all) of the letters may be missing on the screen. If letters are
- missing from a command it doesn't work and even if all letters are
- present you may need to hit the return-key several times to get the
- command to execute.
-
- This may be due to two different processes opening the serial port.
- Both try to read what you type. Sometimes one process (the right one
- --perhaps the shell) reads what you type and at other times the other
- process reads what you type. An example is where the other process is
- for a serial mouse (such as gpm) which doesn't echo what you type. So
- another process running on the same ttySx is eating some of what you
- type. To fix this, use "ps -alx" to see what else is running on your
- ttySx and kill that process.
-
- You might think that lockfiles would prevent two programs from using
- the same serial port at the same time. But neither the terminal nor
- the gpm mouse program uses lockfiles. Since others may need to write
- to your terminal, it's reasonable not to use lockfiles. See Lock-
- Files in the Serial-HOWTO.
-
-
- 18.6. ... respawning too fast: disabled for 5 minutes
-
- 18.6.1. What's happening
-
- You see a message on the console like: "Getty respawning too fast:
- disabled for 5 minutes". Instead of "Getty" it may display a label
- (such as: Id "S2") where S2 is the label for the line in /etc/inittab
- from where from where getty was called.
-
- When getty starts up, it tries to send a login message to the serial
- port. But if there is something seriously wrong, getty will be
- immediately killed. Since the /etc/inittab file line for getty says
- to "respawn", getty is started again, only to be killed again, etc.
- Thus getty respawns over and over. But the operating system
- intervenes and stops this nonsense (for 5 minutes). The following
- sections show possible causes and fixes.
-
-
- 18.6.2. Getty line in /etc/inittab file incorrect
-
- Make sure the the line which calls getty in /etc/inittab is correct.
- A typo in "ttySx" (or "DTxxxx" for uugetty) or in "getty" may cause
- this problem.
- 18.6.3. No modem control signal
-
- If the terminal doesn't send the PC a CD signal on one of the pins of
- the serial port, getty will be killed unless the "local" option has
- been used with getty. So a quick fix is to just use a "local" option
- (-L for agetty, "CLOCAL" in /etc/gettydefs for ps_getty).
-
- Another approach is to determine why CD is not being asserted. In
- many cases the cable to the terminal simply doesn't have a wire for
- the CD pin so you must use the "local" option. If there is a wire for
- the CD pin then there may not be any signal on it until the terminal
- is powered on. Note that the CD pin signal is sometimes supplied by
- the DTR pin of the terminal (or the PC) by using jumper wires inside
- the connector.
-
-
- 18.6.4. No such serial device
-
- If the device (such as /dev/ttyS2) is bogus (doesn't physically exist
- or has been disabled), then getty will be killed. You may use
- "scanport" (Debian only ??) and/or "setserial" to probe for the device
- or try another ttyS. Perhaps the device has been disabled in the
- CMOS. See "Serial-HOWTO".
-
-
- 18.6.5. No serial support
-
- Linux provides serial support either by selecting it when compiling
- the kernel or by loading the serial module: serial.o. This
- "respawning" error happens if serial support has neither been built
- into the kernel nor provided by a serial module. You many use the
- "lsmod" command to see if the serial module is loaded. To see if
- serial support is built into the kernel, check a kernel configuration
- file (in /boot, in the source tree, etc.)
-
-
- 18.6.6. Key shorted
-
- Another possible cause of getty respawning too rapidly is if a
- keyboard key is shorted. This gives the same result as if the key was
- continuously held down. With auto-repeat enabled, this "types"
- thousands of characters to the login prompt. Look for a screen filled
- with all the same character (in some cases, with 2 or more different
- characters).
-
-
- 18.7. Fails Just After Login
-
- If you can login OK but then you can't use the terminal it may be
- because the starting of the login shell has reconfigured the terminal
- (to an incorrect setting) by a command which someone put into one of
- the files that are run when you login and a shell starts. These files
- include /etc/profile and ~/.bashrc. Look for a command starting with
- "stty" or "setserial" and make sure that it's correct. Even if it's
- done OK in one initialization file, it may be reset incorrectly in
- another initialization file that you are not aware of. Ways to get
- into the systems to fix it are to use another terminal or console, use
- a rescue diskette, or type: "linux single" at the lilo prompt which
- puts you into single user mode without running startup files.
-
-
- 18.8. Can't Login
-
- If you get a login prompt but get no response (or perhaps a garbled
- response) to your login attempts a possible cause is that the
- communication is bad one-way from the terminal to the computer. It
- could be a bad or mis-wired cable/connector. If you're not already
- using the "local" option with getty, do so to disable the modem
- control lines. See ``Getty (used in /etc/inittab)''. You might also
- disable hardware flow control (stty -crtscts) if it was enabled. If
- it now works OK then your modem control lines are likely either not
- wired correctly or there's a mistake in your set-up. Some terminals
- allow setting different values (such as baud rate) for send and
- receive so the receive could be OK but the send bad.
-
- You should also (at the console) try "stty < /dev/ttyS1" (if you use
- ttyS1) to see that it's set up correctly. It will often be in raw
- mode (and this is probably OK) with -icanon and -echo etc. If the
- terminal incorrectly set at half-duplex (HDX), then one set of the
- characters you see when you type are coming from the terminal itself.
- If the characters are doubled, then the echos from the computer are OK
- and you may switch to full-duplex to fix this. But if half-duplex is
- set and you only see what looks like normal "echos", then they are not
- coming from the computer as they should be.
-
- If you get a message saying something like "login failed" then if
- there is no error in typing or in the password, there may be some
- restrictions on logins which will not allow you to log in.
- Unfortunately, this message, may not tell you why it failed. See
- ``Login Restrictions''
-
-
- 18.9. Garbled Login Prompt
-
- This may be due to using the wrong character set, transmission errors
- due to too high of a baud rate, incompatible baud rates, incompatible
- parity, or the wrong number of bits per byte. If it's a variety of
- strange characters you have the wrong character set or a high order
- bit is being set by mistake. If words are misspelled, try a lower
- baud rate. For baud, parity, or bits/character incompatibilities you
- see a lot of the same "error character" which represents a real
- character that can't be displayed correctly due to an error in parity
- or baud rate. The "error character" may be an upside-down question
- mark or some other strange looking character such as a rectangle.
-
- If you are using agetty (often just named getty), the agetty program
- will detect and set parity and/or bits/character if you type
- something. Try it with a return to see if it fixes it.
-
-
- 18.10. No Login Prompt
-
- If there's no login prompt displayed after hitting the return-key a
- few times then check the following: Use the "top" or "ps" programs to
- make sure that a getty (or login) process is actually running on the
- terminal. Is the terminal getting power? Is the null modem cable
- plugged in to the correct ports on both the terminal and computer?
-
- Check that getty isn't hanging because there is no CD signal (or no CD
- wire in the cable). If such a CD signal doesn't exist you should have
- specified "local" to getty by either:
-
- · If getty_ps (Redhat, etc.) two CLOCAL flags in /etc/gettydefs (See
- ``getty (part of getty_ps)'').
-
- · If agetty (Debian, etc.) a -L flag in /etc/inittab (See
- ``agetty'').
-
- If getty (or login) isn't running, carefully check the format for
- calling getty in /etc/inittab. Make sure that it includes the current
- runlevel (shown by typing the command "runlevel") and that it is valid
- for your flavor of getty. Sometimes killing getty or login (it will
- restart automatically) helps.
-
-
- 18.10.1. Terminal was working OK
-
- Although hardware failures are possible, the problem is likely due to
- something that someone did by mistake. Did someone do something that
- might have loosened a cable? Did someone modify /etc/inittab or make
- some other change to the software so as to prevent terminal login? If
- this doesn't reveal the cause, continue reading.
-
-
- 18.10.2. More diagnose
-
- The above should solve most cases (unless you've just installed a
- terminal). Other causes include defective hardware or cables (must be
- null-modem), terminal setup at wrong baud-rate, terminal in local
- mode, etc. At this point two different avenues of approach are (you
- may pursue more than one at a time).
-
-
- · ``Diagnose problem from the console''
-
- · ``Measure voltages''
-
-
- 18.10.3. Diagnose problem from the console
-
- One test is to try to copy a something to the terminal (It might be a
- good idea to try this near the start of the installation process
- before setting up getty). You may use the Linux copy command such
- as:"cp file_name /dev/ttyS1". Or your could use: "echo any_word >
- /dev/ttySx". If it doesn't work, use stty to make the interface as
- simple as possible with everything disabled (such as hardware flow
- control: -crtscts; parity, and modem control signals: clocal). Be
- sure the baud rates and the bits/byte are the same. If nothing
- happens verify that the port is alive with a voltmeter per the next
- section.
-
-
- 18.10.4. Measure voltages
-
- If you have a voltmeter handy check for a negative voltage (-4v to
- -15v) at pin 3 (receive data) at the terminal side of the null-modem
- cable. The positive lead of the meter should be connected to a good
- ground (the metal connectors on the ends of cables are often not
- grounded). If there is no such negative voltage then check for it at
- the transmit pin (TxD) on the computer (see ``DB9-DB25'' for the pin-
- out). If it's present there but not at the receive pin (RxD) at the
- terminal, then the cable is bad (loose connection, broken wire, or not
- a null-modem). If voltage is absent at the computer, then its serial
- port is dead. Test it with a software diagnostic test or replace it.
-
- If the serial port is alive, you may want to send a file to it (with
- modem controls disabled) and watch the signal on a voltmeter (or other
- electronic gadget). To check for a transmitted signal with a
- voltmeter, check for a steady negative voltage when the line is idle.
- Then start sending a file (or start getty). On an analog meter you
- should see the needle dropping to almost 0 and fluttering about 0 as
- it measures short-run averages of the bit stream. On a digital meter
- you will not see the fluctuations as well but you can switch to the AC
- scale to see the AC voltage created by the flow of bits. If your
- meter fails to block out DC on the AC scale (the default of most
- analog meters), then you could get a false high AC reading when
- looking at the idle DC of -12 V on the AC scale. Without a meter, you
- could connect a known good device (such as another terminal or an
- external modem) to the serial port and see if it works OK.
-
-
- 18.11. Displays Foreign/Weird Characters/Symbols
-
- Don't confuse this with ``Displays Escape Sequences''. If what you
- type or see on the screen is not what's expected but looks like a
- foreign alphabet, math symbols, line-drawing character, etc. then it
- could be that the many of bytes that are sent to your terminal have
- the high order bit set (when it shouldn't be). You are looking at the
- character set (or part of a character set) which has the high order
- bit set. This may happen if you have the baud rate wrong or parity
- set wrong (per stty). If you have parity set per stty but inside the
- terminal it's 8-bit no-parity, then the high order bit (= parity bit)
- will often be erroneously set. Try stty -F /dev/ttyS? from another
- terminal to check if the baud rate and parity are correct.
-
- Perhaps the wrong character set (font) has been installed. An
- erroneous escape sequence sent to the terminal could have switched
- character sets. If you are using the mapchan program to change the
- keyboard mapping, it could be incorrect.
-
-
- 18.12. Displays Escape Sequences
-
- You may see something like "5;35H22,1" or "3;4v" or "1;24r" or
- "^[[21;6H", etc., etc. Of course, the numbers and letters will be
- different. They will be scattered about (either randomly or in a
- strange sense of order). The display will look a mess and will likely
- have other defects. Some application and commands will result in
- corrupted displays.
-
- What you see are escape sequences (or fragments of them) that were
- sent to your terminal in order to control it, but your terminal didn't
- recognize them and passed them on to the screen. It's likely that the
- program you're using erroneously thinks you are using another type of
- terminal. Thus it sends escape sequences that your terminal doesn't
- understand. This can sometimes do strange things to your display.
- Check that the TERM environment variable is set correctly (type: echo
- $TERM).
-
-
- 18.12.1. Telnet
-
- The problem of getting TERM right can be a bit more complex if you use
- telnet. Telnet doesn't emulate a terminal but passes the value of
- your TERM variable to the remote computer. If the remote computer
- doesn't support your type of terminal, or changes the value of TERM to
- a wrong value (on the remote) then there's trouble. Telnet should
- initially set the value of TERM correctly on the remote. But changes
- to the value of TERM (on the remote) could be caused by an incorrect
- shell configuration file there. The first thing to do is to check the
- value of TERM, both on your computer and on the remote. The above is
- overly simplified since it's possible for your telnet client to
- present the remote server with a list of possible TERM values which
- your computer supports (if telnet knows that your computer can emulate
- more than one terminal type).
-
-
- 18.12.2. Terminal set to display escape sequences
-
- Another possible cause is that your terminal happens to be in a
- special mode where it displays the escape sequences instead of
- executing them. Then you'll also see them on the screen but they will
- display in an orderly fashion. This mode is more precisely, one that
- displays control codes. But since each escape sequence starts with a
- control code (the "escape" character), the whole escape sequence is
- not recognized by the terminal and is passed along to the screen. See
- ``Control Codes''.
-
-
- 18.13. Slow: pauses of several seconds between bursts of characters
-
- You likely have mis-set interrupts> See the Serial-HOWTO section
- starting with "Slow:"
-
-
- 18.14. Terminal doesn't scroll
-
- One reason may be that something is wrong with terminfo. Another
- reason could be that you are outside the scrolling region set for the
- terminal. Some stupid programs just assume that your terminal has 24
- lines and set the scrolling region for 24 lines (by an escape sequence
- sent to the terminal) without consulting terminfo to see how many
- lines there actually are. Then when you use another program it may
- leave the cursor on line 25 where it becomes trapped and the terminal
- will not scroll. To avoid this problem, create an environment
- variable "export LINES=25" and also "stty -F /dev/ttySx rows 25".
- Then the programs that assume 24 lines will hopefully use 25 lines set
- the scrolling region accordingly.
-
-
- 18.15. Serial Monitoring/Diagnostics
-
- A few Linux programs will monitor the modem control lines and indicate
- if they are positive (1) or negative (0).
-
- · statserial (in Debian distribution)
-
- · serialmon (doesn't monitor RTS, CTS, DSR but logs other functions)
-
- · modemstat (only works on Linux PC consoles. Will coexist with the
- command line)
-
- You may already have them. If not, go to Serial Software
- . When using
- these, bear in mind that what you see is the state of the lines at
- the host computer. The situation at the terminal will be different
- since some wires are often missing from cables while other wires
- cross over. As of June 1998, I know of no diagnostic program in
- Linux for the serial port.
-
-
- 18.16. Local Mode
-
- In local mode, the terminal disconnects from the computer and behaves
- like a typewriter (only it doesn't type on paper but on the screen).
- Going back into on-line mode reconnects to the computer allowing you
- to resume activities at the same point where you left off when you
- went into "local". This is useful both for testing the terminal and
- for educational purposes. For some terminals there is no "local
- mode" but "block mode" may substitute for it. If there is no "block
- mode", "half duplex" mode might work, except that what you type gets
- sent to the computer also. In this case the computer may echo the
- characters sent to it resulting in two characters displayed on the
- screen for every character you type. To prevent this you could shut
- down the computer, disconnect the RS-232 cable, etc.
-
- When in local mode you may type escape sequences (starting with the
- ESC key) and observe what they do. If the terminal doesn't work
- correctly in local mode, it's unlikely that it will work correctly
- when connected to the computer. If you're not exactly sure what an
- escape sequence does, you can try it out in local mode. You might
- also use it for trying out a terminal that is for sale. To get into
- local mode on some terminals you first enter set-up mode and then
- select "local" from a menu (or press a certain key). See ``Getting
- Into Set-Up (Configuration) Mode''.
-
-
- 18.17. Serial Electrical Test Equipment
-
- 18.17.1. Breakout Gadgets, etc.
-
- While a multimeter (used as a voltmeter) may be all that you need for
- just a few serial ports, simple special test equipment has been made
- for testing serial port lines. Some are called "breakout ... " where
- breakout means to break out conductors from a cable. These gadgets
- have a couple of connectors which connect to serial port connectors
- (either at the ends of serial cables or at the back of a PC). Some
- have test points for connecting a voltmeter. Others have LED lamps
- which light when certain modem control lines are asserted (turned on).
- The color of the light may indicate the polarity of the signal
- (positive or negative voltage). Still others have jumpers so that you
- can connect any wire to any wire. Some have switches.
-
- Radio Shack sells (in 2002) a "RS-232 Troubleshooter" (formerly called
- "RS-232 Line Tester") Cat. #276-1401. It checks TD, RD, CD, RTS, CTS,
- DTR, and DSR. A green light means on (+12 v) while red means off (-12
- v). They also sell a "RS-232 Serial Jumper Box" Cat. #276-1403.
- This permits connecting the pins anyway you choose. Both these items
- are under the heading of "Peripheral hookup helpers". Unfortunately,
- they are not listed in the index to the printed catalog. They are on
- the same page as the D type connecters so look in the index under
- "Connectors, Computer, D-Sub". A store chain named "Active
- Components" may have them.
-
-
- 18.17.2. Measuring voltages
-
- Any voltmeter or multimeter, even the cheapest that sells for about
- $10, should work fine. Trying to use other methods for checking
- voltage is tricky. Don't use a LED unless it has a series resistor to
- reduce the voltage across the LED. A 470 ohm resistor is used for a
- 20 ma LED (but not all LED's are 20 ma). The LED will only light for
- a certain polarity so you may test for + or - voltages. Does anyone
- make such a gadget for automotive circuit testing?? Logic probes may
- be damaged if you try to use them since the TTL voltages for which
- they are designed are only 5 volts. Trying to use a 12 V incandescent
- light bulb is not a good idea. It won't show polarity and due to
- limited output current of the UART it probably will not even light up.
-
- To measure voltage on a female connector you may plug in a bent paper
- clip into the desired opening. The paper clip's diameter should be no
- larger than the pins so that it doesn't damage the contact. Clip an
- alligator clip (or the like) to the paper clip to connect up. Take
- care not to touch two pins at the same time with any metal object.
-
-
- 18.17.3. Taste voltage
-
- As a last resort, if you have no test equipment and are willing to
- risk getting shocked (or even electrocuted) you can always taste the
- voltage. Before touching one of the test leads with your tongue, test
- them to make sure that there is no high voltage on them. Touch both
- leads (at the same time) to one hand to see if they shock you. Then
- if no shock, wet the skin contact points by licking and repeat. If
- this test gives you a shock, you certainly don't want to use your
- tongue.
- For the test for 12 V, Lick a finger and hold one test lead in it.
- Put the other test lead on your tongue. If the lead on your tongue is
- positive, there will be a noticeable taste. You might try this with
- flashlight batteries first so you will know what taste to expect.
-
-
-
- 19. Repair & Diagnose
-
- Repairing a terminal has much in common with repairing a monitor
- and/or keyboard. Sometimes the built-in diagnostics of the terminal
- will display on the screen. By the symptoms, one may often isolate
- the trouble to one of the following: bad keyboard, CRT dead, power
- electronics failure (distorted display), or digital electronics
- failure. It's best to have a service manual, but even if you don't
- have one, you can often still repair it.
-
-
- 19.1. Repair Books & Websites
-
- 19.1.1. Books
-
- Bigelow, Stephen J.: Troubleshooting & Repairing Computer Monitors,
- 2nd edition, McGraw-Hill, 1997. Doesn't cover the character
- generation electronics nor the keyboard.
-
-
- 19.1.2. Websites
-
- The FAQ for the newsgroup:
- sci.electronics.repair is long and comprehensive, although it doesn't
- cover terminals per se. See the section "Computer and Video
- Monitors". Much of this information is applicable to terminals as are
- the sections: "Testing Capacitors", "Testing Flyback Transformers",
- etc. Perhaps in the future, the "info" on repair in this HOWTO will
- consist mainly of links to the above FAQ (or the like). Shuford's
- repair archive
- of
- newsgroup postings on terminal repair is another source of info.
-
-
- 19.2. Safety
-
- CRT's use high voltage of up to 30,000 volts for color (less for
- monochrome). Be careful not to touch this voltage if the set is on
- and the cover off. It probably won't kill you even if you do since
- the amount of current it can supply is limited. But it is likely to
- badly burn and shock you, etc. High voltage can jump across air gaps
- and go thru cracked insulation so keep your hands a safe distance from
- it. You should notice the well-insulated high voltage cable connected
- to one side of the picture tube. Even when the set is off, there is
- still enough residual voltage on the picture tube cable connection to
- give you quite a shock. To discharge this voltage when the set is
- unplugged use a screwdriver (insulated handle) with the metal blade
- grounded to the picture tube ground cable with a jumper wire. Don't
- use chassis ground.
-
- The lower voltages (of hundreds of volts) can be even more dangerous
- since they are not current limited. It is even more dangerous if your
- hands are wet or if you are wearing a metal watchband, ring or the
- like. In rare cases people have been killed by it so be careful. The
- lowest voltages of only several volts on digital circuitry are fairly
- safe but don't touch anything (except with a well insulated tool)
- unless you know for sure.
-
-
- 19.3. Appearance of Display
-
- If the display is too dim, turn up the brightness and/or contrast.
- using knobs on the exterior of the unit (if they exist). If the
- width, height or centering is incorrect, there are often control knobs
- for these. For some older terminals one must press an arrow key (or
- the like) in set-up mode.
-
- You may need to remove the cover to make adjustments, especially on
- older models. You could arrange things so that a large mirror is in
- front of the terminal so as to view the display in the mirror while
- making adjustments. The adjustments to turn may be on a printed
- circuit board. While a screwdriver (possibly Phillips-head) may be
- all that's needed, inductors may require special TV alignment tools
- (plastic hex wrenches, etc.). The abbreviated name of the adjustment
- should be printed on the circuit board. For example, here are some
- such names:
-
-
- · V-Size adjusts the Vertical height (Size)
-
- · H-Size adjusts the Horizontal width (Size). It may be an inductor.
-
- · V-Pos adjusts the Vertical Position
-
- · H-Pos adjusts the Horizontal Position
-
- · V-Lin adjusts Vertical Linearity (Use if width of scan lines
- differs at the top and bottom of the screen)
-
- · V-Hold adjusts Vertical Hold (Use if screen is uncontrollable
- scrolling)
-
- · Bright adjusts brightness (an external knob may also exist)
-
- · Sub-Bright adjusts brightness of subdued intensity mode (often the
- normal mode: dimmer than bold or bright mode).
-
- Changing linearity may change the size so that it will need to be
- readjusted. A terminal that has been stored for some time may have a
- small display rectangle on the screen surrounded by a large black
- Before adjusting it, leave the terminal on for a while since it will
- likely recover some with use (the black borders will shrink).
-
-
- 19.4. Diagnose
-
- 19.4.1. Terminal Made a Noise or Smoked
-
- If the terminal made some noise just before it failed (or when you
- turn it on after it failed) that noise is a clue to what is wrong. If
- you hear a noise or see/smell smoke, immediately turn the terminal off
- to prevent further damage. A pop noise may be a capacitor exploding
- or a fuse blowing. A buzzing noise is likely due to arcing. The
- problem may be in the high voltage power supply of several thousand
- volts.
-
- Remove the cover. Look for discoloration and bulging/cracked
- capacitors. If the bad spot is not evident, turn it on again for a
- short time and look for smoking/arcing. For arcing, a dimly lit room
- will help find it. The high voltage cable (runs between the flyback
- transformer and the side of the picture tube) may have broken
- insulation that arcs to ground. Fix it with high-voltage insulating
- dope, or special electrical tape designed say for 10,000 volts.
-
-
- The flyback transformer (high voltage) may make only a faint clicking
- or sparking noise if it fails. You may not hear it until you turn the
- terminal off for a while and then turn it back on again. To track
- down the noise you may use a piece of small rubber tubing (such as
- used in automobiles) as a stethoscope to listen to it. But while you
- are listening for the noise, the terminal is suffering more damage so
- try find it fast (but not so fast as to risk getting shocked).
-
- A shorted power supply may cause a fuse to blow. Replacing a blown
- fuse may not solve the problem as the same short may blow the fuse
- again. Inspect for any darkened spots due to high heat and test those
- components. Shorted power transistors may cause the fuse to blow.
- They may be tested with a transistor checker or even with an ohm-
- meter. Use the low ohm scale on an ohm-meter so that the voltage
- applied by the meter is low. This will reduce the possible damage to
- good components caused by this test voltage.
-
- If the terminal has been exposed to dampness such as being stored in a
- damp place or near a kitchen with steam from cooking, a fix may be to
- dry out the unit. Heating a "failed" flyback transformer with a blow
- dryer for several minutes may restore it.
-
-
- 19.4.2. Terminal Made No Noise
-
- A blank screen may be due to someone turning the brightness control to
- the lowest level or to aging. The next thing to do is to check the
- cables for loose or broken connections. If there is no sign of power,
- substitute a new power cord after making sure that the power outlet on
- the wall is "hot".
-
- If the keyboard is suspected, try it on another terminal of the same
- type or substitute a good keyboard. Wiggle the keyboard cable ends
- and the plug. Wires inside cables may break, especially near their
- ends. If the break is verified by wiggling it (having the problem go
- on and off in synchronization with the wiggles), then one may either
- get a new cable or cut into the cable and re-solder the breaks, etc.
-
- One of the first things to do if the keyboard works is to put the
- terminal into ``Local Mode''. If it works OK in local, then the
- problem is likely in the connection to the host computer (or incorrect
- interface) or in the UART chips of the terminal.
-
-
- 19.5. Detective work
-
- By carefully inspecting the circuitry, one may often find the cause of
- the problem. Look for discoloration, cracks, etc. An intermittent
- problem may sometimes be found by tapping on components with a ball-
- point pen (not the metal tip of course). A break in the conductor of
- a printed circuit board may sometimes be revealed by flexing the
- board. Solder that looks like it formed a drop or a solder joint with
- little solder may need re-soldering. Soldering may heat up
- transistors (and other components) and damage them so use a heat sink
- if feasible. One failure may cause others, so unless you find the
- original cause, the failure may reoccur.
-
- If you have a common brand of terminal, you may be able to search the
- Internet (including newsgroup postings) to find out what the most
- frequent types of problems are for your terminal and perhaps
- information on how to fix it. If you find that a certain component is
- bad you may search for this component (for example R214 wyse) and
- hopefully find a report by someone else who had the same problem.
- Such a report may indicate other components that failed at the same
- time. If a component is damaged so badly that its value can't be
- read, then you might find it on the Internet. The manufacturer may
- have on-line data that search engines don't index.
-
- To see if the digital electronics work, try (using a good keyboard)
- typing at the bad terminal. Try to read this typing at a good
- terminal (or the console) using the copy command or with a terminal
- communication program such as minicom. You may need to hit the return
- key at the terminal in order to send a line. One may ask the bad
- terminal for its identity etc. from another terminal. This will show
- if two-way communication works.
-
-
- 19.6. Error Messages on the Screen
-
- You are in luck if you see an error message on the screen. This
- usually happens when you first turn the terminal on.
-
-
- 19.6.1. Keyboard Error
-
- This usually means that the keyboard is not plugged in, or that the
- connection is loose. For more serious problems see ``Keyboards''
-
-
- 19.6.2. Checksum Error in NVR
-
- NVR is "Non-Volatile RAM". This means that the NVR where the set-up
- information is stored has become corrupted. The terminal will likely
- still work but the configuration that was last saved when someone last
- configured the terminal has likely been lost. Try configuring again
- and then save it. It might work. On very old terminals (early
- 1980's) there was a battery-powered CMOS to save the configuration so
- in this case the problem could be just a dead battery. Sometimes the
- EEPROM chip (no battery needed) goes bad after too many saves. It may
- be hard to find. If you can't fix it you are either stuck with the
- default configuration or you may have escape sequences sent to the
- terminal when you start it up to try to configure it.
-
-
- 19.7. Capacitors
-
- Electrolytic capacitors have a metal shell and are may become weak or
- fail if they set for years without being used. Sometimes just leaving
- the terminal on for a while will help partially restore them. If you
- can, exercise any terminals you have in storage by turning them on for
- a while every year or so.
-
- Note that cheap electrolytic capacitors designed for use in audio
- circuits may fail if used in high frequency horizontal circuitry. For
- this, you need low resistance (low ESR) capacitors. Replace non-
- polarized capacitors (NP) with the same (or with "bi-polar").
-
- If the terminal display takes several minutes of warmup before it's OK
- then it's likely that you have one or more bad electrolytic
- capacitors. One trick to find the bad one is to parallel each
- suspected bad one with a good one (of at least the same voltage rating
- and capacitance of roughly the same order of magnitude). If the
- display improves a lot when you do this, then you've likely found the
- bad capacitor. Be careful not to get shocked when doing this. The
- actual voltage with respect to ground may be much higher than the
- voltage rating of the capacitor.
-
-
- 19.8. Keyboards
-
-
-
- 19.8.1. Interchangeability
-
- The keyboards for terminals are not the same as keyboards for PC's.
- The difference is not only in the key layout but in the codes
- generated when a key is pressed. Also, keyboards for various brands
- and models of terminals are not always interchangeable with each
- other. Sometimes one get an "incompatible" keyboard to partially work
- on a terminal: All the ASCII keys will work OK, but special keys such
- as set-up and break will not work correctly.
-
-
- 19.8.2. How They Work
-
- Most keyboards just make a simple contact between two conductors when
- you press a key. Electronics inside a chip in the keyboard converts
- this contact closure into a code sent over the keyboard's external
- cable. Instead of having a separate wire (or conductor) going from
- each key to the chip, the following scheme is used: Number the
- conductors say from 1-10 and A-J. For example: conductor 3 goes to
- several keys and conductor B goes to several keys, but only one key
- has both conductors 3 and B going to it. When that key is pressed, a
- short circuit is established between 3 and B. The chip senses this
- short and knows what key has been pressed. Such a scheme reduces the
- number of conductors needed (and reduces the number of pins needed on
- the chip). It's a similar scheme to what is called a "crossbar
- switch".
-
-
- 19.8.3. Modern vs Old Keyboards
-
- While the modern keyboard and the old fashioned type look about the
- same, the mechanics of operation are different. The old ones have
- individual key switches under the key-caps with each switch enclosed
- in a hard plastic case. The modern ones use large flexible plastic
- sheets (membrane) the size of the keyboard. A plastic sheet with
- holes in it is sandwiched between two other plastic sheets containing
- printed circuits (including contact points). When you press a key,
- the two "printed" sheets are pressed together at a certain point,
- closing the contacts printed on the sheets at that point.
-
-
- 19.8.4. One Press Types 2 Different Characters
-
- If, due to a defect, conductors 3 and 4 become shorted together then
- pressing the 3-B key will also short 4 and B and the chip will think
- that both keys 3-B and 4-B have been pressed. This is likely to type
- 2 different characters when all you wanted was one character.
-
-
- 19.8.5. Keyboard doesn't work at all
-
- If none of the keys work try another keyboard (if you have one) to
- verify that the keyboard is the problem. One cause is a broken wire
- inside the cord (cable) that connects it to the terminal. The most
- likely location of the break is at either end of the cord. Try
- wigging the ends of the cord while tapping on a key to see if it works
- intermittently. If you find a bad spot, you may carefully cut into
- the cord with a knife at the bad spot and splice the broken conductor.
- Sometimes just a drop of solder will splice it. Seal up the cord with
- electrical tape, glue, or caulk. A keyboard that has gotten wet may
- not work at all until it's dry.
-
-
-
- 19.8.6. Typing b displays bb, etc. (doubled)
-
- If all characters appear double there is likely nothing wrong with the
- keyboard. Instead, your terminal has likely been incorrectly set up
- for half-duplex (HDX or local echo=on) and every character you type is
- echoed back both from the electronics inside your terminal and from
- your host computer. If the two characters are not the same, there may
- be a short circuit inside your keyboard. See ``One Press Types 2
- Different Characters''
-
-
- 19.8.7. Row upon row of the same character appears
-
- This may happen when auto-repeat is enabled and a key is held pressed
- down (or the like). It may be a key that sticks down when typed or it
- could be an electrical short that has the same effect.
-
-
- 19.8.7.1. Key sticks in down position (individual switches)
-
- First try tapping on it hard several times but it's not likely to fix
- it. Next, your can either remove the keycap (if it is removable) and
- squirt a little cleaner on the push rod or work the key up and down
- while pushing on it sideways (or both). If this doesn`t work you may
- need to take the switch apart and clean the components.
-
- If you decide to remove the keycap see ``Keyboards with individual
- switches''. Press repeatedly on the push rod until it works OK and
- also displays its character on the screen. At first, the cleaner may
- cause the key to fail to display its character. Some keys stick due
- to stickiness on the keycap bottom surface.. If the key sticks in the
- fully down position this could be the problem. So you might need to
- clean this this area too.
-
- If you decide to push it sideways, use a small screwdriver to push
- sideways with while pushing the key up and down with both your finger
- and the screwdriver. You should push it sideways in one of the four
- directions and try different directions. What you are doing by this
- is attempting to force out a foreign particles that are rubbing on the
- side of the key's push-rod and making it stick. Again, the problem
- may return later.
-
- Always test the key just after fixing it and a short time later. To
- test the key, push it down very slowly and see if it sticks. Also
- push it sideways a little as you're pushing it down. If you hit it
- fast or push it straight down, then you may not observe the
- stickiness. This test will detect a key that seemingly works OK but
- is likely to cause trouble later on.
-
-
- 19.8.7.2. Key electrically shorted
-
- If you suspect that a key is shorted out, fix it by cleaning the
- contacts per ``Cleaning Keyboard Contacts''. If this problem happens
- at the login prompt see ``Key shorted''.
-
-
- 19.8.8. Liquid spilled on the keyboard
-
- If water or watery liquid has been spilled on the keyboard (or if it
- was exposed to rain, heavy dew, or dampness) some (or all) keys may
- not work right. The dampness may cause a key to short out (like it
- was pressed down all the time) and you may see the screen fill up with
- that letter if auto-repeat is enabled. If it's gotten wet and then
- partially (or fully) dried out, certain keys may not work due to
- deposits on the contact surfaces. For the modern type of keyboard,
- one may readily take apart the plastic sheets inside and dry/clean
- them. For the old type one may let it dry out in the sun or oven (low
- temp.). When it's dry it may still need contact cleaner on some keys
- as explained below.
-
-
- 19.8.9. Cleaning keyboard contacts
-
- 19.8.9.1. Keyboards with membranes
-
- On some newer keyboards, the plastic sheets (membranes) are easy to
- remove for inspection and cleaning if needed. You only need to remove
- several screws to take apart the keyboard and get to the sheets. On
- some old IBM keyboards the sheets can't be removed without breaking
- off many plastic tabs which will need to be repaired with glue to put
- back (probably not worthwhile to repair). Such a keyboard may
- sometimes be made to work by flexing, twisting, and/or pounding the
- assembly containing the plastic sheets.
-
-
- 19.8.9.2. Keyboards with individual switches
-
- What follows is for older keyboards that have separate hard plastic
- switches for each key. Before going to all the work of cleaning
- electrical contacts first try turning the keyboard upside-down and
- working the bad keys. This may help dislodge dirt, especially if you
- press the key hard and fast to set up vibration. Pressing the key
- down and wiggling it from side to side, etc. often helps.
-
- If this doesn't work, you may try to clean the key switch with a
- liquid contact cleaner (available at electronic supply stores) which
- usually comes in a spay can. To get to the switch, you first need to
- remove the key-cap (the square that you hit with your finger while
- typing). Warning: Key-caps on modern keyboards can't be removed.
- Often, the key-caps may be removed by prying them upward using a small
- screwdriver with the tip placed under a key while preventing excessive
- tilting with a finger. There exists a special tool known as keycap
- puller but you can get by without it. The key-cap may tilt a bit and
- wobble as it comes loose. It may even fly up and onto the floor.
-
- Then you may have two choices on how to clean the contacts: Use
- contact cleaner spray directly on top of the key switch, or take the
- key switch apart and clean it (the best way if it comes apart easily).
- Still another choice is to replace the key switch with a new or used
- one but this is often more work (and more cost if you have to buy the
- switch).
-
- Directly spraying contact cleaner into the top of the key switch is
- the fastest method but the cleaner may not reach the contacts it's
- supposed to clean. Before spraying, clean the area around it a
- little. With the keyboard live (or with the key contacts connected to
- an ohm-meter) use the plastic tube which came with the spray to squirt
- cleaner so it will get inside the key switch. Try to move the key
- push rod up and down while spraying. Don't let the cleaning liquid
- get under nearby keys where it may pick up dust and then seep (with
- the dust) into adjacent key switches. If you make this mistake you
- may fix one key but damage nearby keys. If this should happen,
- immediately work (repeatedly press) the affected nearby keys until
- they continue to work OK.
-
- You might tilt the keyboard so that the cleaner flows better into the
- contacts. For the CIT101e terminal with an Alps keyboard, this means
- tilting the digit row up toward the ceiling. While moving the key
- switch up and down with a pen or small screwdriver handle avoid
- getting the toxic cleaner liquid on your skin (or wear gloves). You
- might try turning the keyboard upside-down while working the key to
- drain off remaining cleaner. I don't usually do this. The more
- cleaner you squirt in the more likely it will fix it but it is also
- more likely to do more damage to the plastic or contaminate adjacent
- keys, so use what you think is just enough to do the job. Once the
- key works OK, work it up and down a little more and test it a half
- minute later, etc. to make sure it will still work OK.
-
- Sometimes a key works fine when the contacts inside are saturated with
- contact cleaner liquid. But when the liquid dries a few minutes later
- then the resulting scale deposit left from the evaporation of the
- cleaning liquid on the contacts, prevents good contact. Then the key
- may work erratically (if at all). Operating the key when the liquid
- is drying inside may help. Some switches have the contacts nearly
- sealed inside so little if any contact cleaner reaches the contacts.
- The cleaner that does get to the contacts may carry contamination with
- it (cleaning around the tops before spraying helps minimize this).
-
- If you need to disassemble the key switch, first inspect it to see if
- it comes apart (and if so, how). Sometimes one may remove the cover
- of the switch without removing the switch from the keyboard. To do
- this pry up (or pull up) the top of the key switch after prying apart
- thin plastic tabs that retain it. You may be able to use two small
- screwdrivers for this and be able to pry up the switch while prying
- apart the plastic retaining tabs. Don't pry to hard or you may break
- the plastic. If this can't be done, you may have to unsolder the
- switch and remove it in order to take it apart (or replace it). Once
- the switch has been taken apart you still may not be able to see the
- contacts if the contact surfaces are sandwiched together (nearly
- touching). You may get contact cleaner on the contacts by squirting a
- little cleaned on an edge where it can penetrate into the contacts as
- you work the contacts open and closed with a screwdriver.
-
- If the above doesn't work. Slightly prying apart the conducting
- surfaces while applying cleaner might help. There may be some kind of
- clip holding the contact surfaces together which needs to be removed
- before prying. With cleaner on the contacts, work them. Tilting the
- keyboard or inverting it may help. Take care not to loose small parts
- as they may fly up into the air when taking apart a key switch. As a
- last resort, you may try bending the moving part that the push-rod
- pushes so as to make a stronger contact. In my terminal, this part
- looks like the electrical contact but it just pushes the real
- electrical contact (thru a thin insulator).
-
- When putting the key switch back together, make sure that the spring
- is in the right place. If, after you assemble the switch, the key
- pushes down too hard or too easy, the spring is likely not positioned
- right. If the spring is supposed to be recessed into a hole on the
- push rod, one way to temporarily "glue" the spring into the push-rod
- is to use a half-drop of water on the end of the spring. Then insert
- this end into the push rod and assemble quickly before the water
- dries. This should keep the spring from falling out of the push rod
- during assembly. Instead of using water, working on the keyboard when
- it's standing on end (or upside-down) will keep the spring from
- falling out during assembly.
-
-
- 20. Appendix A: General
-
- 20.1. List of Linux Terminal Commands
-
- 20.1.1. Sending a command to the terminal
-
-
- · ``setterm'': long options
-
-
- · ``tput'': terse options
-
- · tset: initializes only
-
- · clear: clears screen
-
- · setterm -reset: sends reset string
-
-
- 20.1.2. Configuring the terminal device driver
-
-
- · ``Setserial'':
-
- · ``Stty''
-
-
- 20.1.3. Terminfo
-
-
- · ``Terminfo Compiler (tic)'' terminfo compiler & translator
-
- · toe: shows list of terminals for which you have terminfo files
-
- · ``infocmp'' compares or displays terminfo entries
-
-
- 20.1.4. Other
-
-
- · gitkeys: shows what bytes each key sends to the host.
-
- · tty: shows what tty port you are connected to.
-
- · set (or tset -q): shows the value of TERM, the terminfo entry name
-
- · ``tset'': sets TERM interactively and initializes
-
-
- 20.2. The Internet and Books
-
- 20.2.1. Terminal Info on the Internet
-
-
-
- · Shuford's Website
- at the
- University of Tennessee has a great deal of useful information
- about text terminals.
-
- · VT terminal information and history
-
- · Boundless purchased the
- VT and Dorio terminal business from DEC. To get Specs select
- either ADDS, VT, or DORIO links. Then select a "data sheet" link.
- Then on the data sheet select the "Go to Specs" link.
-
- · Wyse has detailed info (such as escape sequences) in it's knowledge
- base. It's not as complete as a real manual since it mainly cover
- "native" personality. Wyse text-terminals database
- For
- current models see Wyse terminals
- .
-
- · Teemworld Escape Sequences
- is a list of escape sequences (and control codes) for some terminal
- emulations (including VT 100, 300, 420, and Wyse).
-
- · ncurses FAQ
-
- · comp.terminals is the newsgroup for terminals
-
-
- 20.2.2. Books related to terminals
-
-
-
- · EIA-232 serial port see ``EIA-232 (RS-232) Books''.
-
- · Repair see ``Repair Books & Websites''.
-
- · Terminfo database see ``Termcap Documents''
-
-
- 20.2.3. Entire books on terminals
-
- As far as I know, there is no satisfactory book on text terminals
- Although this HOWTO has been published as a book, I don't suggest that
- that you buy it if you have access to the online version which I'm
- improving on every month or so. The following are mainly of
- historical interest:
-
-
- · Handbook of Interactive Computer Terminals by Duane E. Sharp;
- Reston Publishing Co. 1977. (mostly obsolete)
-
- · Communicating with Display Terminals by Roger K. deBry; McGraw-Hill
- 1985. (mostly on IBM synchronous terminals)
-
- The "HANDBOOK ... " presents brief specifications of over 100
- different models of antique terminals made in the early 1970's by over
- 60 different companies. It also explains how they work physically but
- has a diagram for a CRT which erroneously shows electrostatic
- deflection of the electron beam (p. 36). Terminals actually used
- magnetic deflection (even in the 1970's). This book explains a number
- of advanced technical concepts such as "random scan" and "color
- penetration principle".
-
- The "COMMUNICATING ... " book in contrast to the "Handbook ... "
- ignores the physical and electronic details of terminals. It has an
- entire chapter explaining binary numbers (which is not needed in a
- book on terminals since this information is widely available
- elsewhere). It seems to mostly cover old IBM terminals (mainly the
- 3270) in block and synchronous modes of operation. It's of little use
- for the commonly used ANSI terminals used today on Unix-like systems.
- Although it does discuss them a little it doesn't show the various
- wiring schemes used to connect them to serial ports.
-
-
- 20.2.4. Books with chapters on terminals
-
- These chapters cover almost nothing about the terminals themselves and
- their capabilities. Rather, these chapters are mostly about how to
- set up the computer (and its terminal driver) to work with terminals.
- Due to the differences of different Unix-like systems, much of the
- information does not not apply to Linux.
-
-
- · Unix Power Tools by Jerry Peck et. al. O'Reilly 1998. Ch. 5
- Setting Up Your Terminal, Ch. 41: Terminal and Serial Line
- Settings, Ch. 42: Problems With Terminals
-
- · Advanced Programming in the Unix Environment by W. Richard Stevens
- Addison-Wesley, 1993. Ch. 11: Terminal I/O, Ch. 19: Pseudo
- Terminals
-
- · Essential System Administration by Aleen Frisch, 2nd ed. O'Reilly,
- 1998. Ch. 11: Terminals and Modems.
-
- The "UNIX POWER TOOLS" book has 3 short chapters on text terminals.
- It covers less ground than this HOWTO but gives more examples to help
- you.
-
- The "ADVANCED PROGRAMMING ... " Chapter 11 covers only the device
- driver included in the operating system to deal with terminals. It
- explains the parameters one gives to the stty command to configure the
- terminal.
-
- The "ESSENTIAL SYSTEM ..." book's chapter has more about terminals
- than modems. It seems well written.
-
-
- 20.3. Non-Linux OSs
-
- Under Microsoft's DOS one may use the DOS command "ctty COM2" so that
- the DOS command line will display on a serial terminal (on COM2 in
- this example). Unfortunately one can then no longer use the computer
- monitor since MS DOS is not a multiuser operating system. Nor can
- more than one terminal be used. So this capability is of little (if
- any) benefit. If you emulate DOS under Linux with the free dosemu,
- it's reported that you can run several terminals (multiuser). But
- it's reported that PCTerm emulation doesn't work with it (yet ??).
-
- While MS didn't create a "multiuser DOS" OS, others did. This permits
- the use of many terminals on one DOS PC. It's compatible with most
- MS-DOS software. One multiuser DOS OS is named "REAL/32". The
- terminal's "pcterm" emulation is used here. There also may be a
- "scan" (scancodes) setup mode which needs to be set. Other OSs such
- as PICK, PC-MOS, and Concurrent DOS were/are multiuser and support
- terminals.
-
- There are 3 programs for Linux which let you run Windows applications
- on a Linux PC: free: Wine, non-free: VMware and NeTraverse. Can they
- use text-terminals under DOS? Wine can't since it doesn't have a DOS
- mode. The other two require you to run the MS Windows OS software as
- a "guest OS". The guest MS Windows OS has a DOS mode but it's not of
- much use for text-terminals since it's not multiuser.
-
- For other unix-like OSs, the configuration of the host computer for
- terminals is usually significantly different than for Linux. Here are
- some links to on-line manuals for unix-like systems.
-
-
- · SCO's OpenServer Adding Serial Terminals
- in SCO
- OpenServer Handbook.
-
- · Hewlett-Packard's HP-UX "Configuring Terminals and Modems" (Url to
- it is dead.)
-
-
- 21. Appendix B: Escape Sequence Commands Terminology
-
- These are sometimes called "control sequences". This section of Text-
- Terminal-HOWTO is incomplete (and may never be complete as there are
- such a huge number of control sequences). This section is for
- reference and perhaps really belongs in something that would be called
- "Text-Terminal-Programming-HOWTO".
- An example of an ANSI standard escape sequence is ESC[5B which moves
- the cursor down 5 lines. ESC is the Escape character. The parameter
- 5 is included in the sequence. If it were 7 the cursor would move
- down 7 lines, etc. A listing for this sequence as "move cursor down x
- lines: ESC[xB" is easy to to understand. But command jargon such as:
- "tertiary device attribute request" is less comprehensible. This
- section will try to explain some of the more arcane jargon used for
- escape sequence commands. A full listing (including the escape
- sequence codes for the ANSI standard) is a "wish list" project. Since
- many escape sequences do the same thing as is done when setting up the
- terminal with ``Set-Up Options'', such escape sequences options will
- not be repeated here.
-
-
- 21.1. Esc Sequence List
-
- For a list of many (but not all) escape sequences for various
- terminals see Teemworld Escape Sequences
- . These are used for terminal
- emulation and are not always the same as on the corresponding real
- terminal. A list for VT (not maintained) may be found at Emulators
- FAQ .
- Search for "VT". For downloading manuals see VT Manuals
- .
-
-
- 21.2. 8-bit Control Codes
-
- Table of 8-bit DEC control codes (in hexadecimal). Work on VT2xx or
- later. CSI is the most common.
-
-
- ACRONYM FULL_NAME HEX REPLACES
- IND Index (down one line) 84 ESC D
- NEL Next Line 85 ESC E
- RI Reverse Index (one line up) 8D ESC M
- SS2 Single Shift 2 8E ESC N
- SS3 Single Shift 3 8F ESC O
- DCS Device Control String 90 ESC P
- CSI Control Sequence Introducer) 9B ESC [
- ST String Terminator 9C ESC \
-
-
-
- 21.3. Printer Esc
-
-
-
- · Auto Print on/off: When on, data from the host is also teed (sent)
- to the printer port of the terminal (and also shows on the terminal
- screen).
-
- · Print Controller on/off: When on, data from the host is sent only
- to the printer (nothing shows on the terminal screen).
-
-
- 21.4. Reports
-
- These sequences are usually a request sent from the host to request a
- report from the terminal. The terminal responds by sending a report
- (actually another escape sequence) to the host which has embedded in
- it certain values telling the host about the current state of the
- terminal. In some cases a report may be sent to the host even if it
- wasn't asked for. This sometimes happens when set-up is exited. By
- default no unsolicited reports should be sent.
-
-
- · Request for Status (Report Operating Status): Meaning of replies
- for VT100 is either "I'm OK" or "I'm not OK"
-
- · Request for Device Attributes: The "device" is usually the
- printer. Is there a printer? Is it ready?
-
- · Reqest for Tertiary Device Attributes (VT): Reply is report that
- was entered during set-up. The tertiary device is the 3rd device
- (the printer or auxiliary port device ??). The 1st device may be
- the host computer and the 2nd device the terminal.
-
- · Request for Terminal Parameters: What is the parity, baud rate,
- byte width, etc. This request doesn't seem to make much sense,
- since if the host didn't already know this it couldn't communicate
- with the terminal or send a reply.
-
-
- 21.5. Cursor Movements
-
- The cursor is where the next character received from the host will be
- displayed. Most of the cursor movements are self-explanatory. "index
- cursor" means to move the cursor down one line. Cursor movements may
- be relative to the current position such as "move 4 spaces left" or
- absolute such as "move to row 3, column 39". Absolute is called
- "Direct Cursor Positioning" or "Direct Cursor Addressing".
-
- The home position is row 1 col. 1 (index origin is 1). But where this
- home position is on the physical screen is not completely clear. If
- "Cursor Origin Mode" = "Relative Origin Mode" is set, then home is at
- the top of the scrolling region (not necessarily the top of the
- screen) at the left edge of the screen. If "Absolute Origin Mode" is
- set (the same as unsetting any of the two modes in the previous
- sentence) then home is at the upper left corner of the screen. On
- some old terminals if "Cursor Origin Mode" is set it means that it's
- relative.
-
-
- 21.6. Pages (definition)
-
- See ``Pages'' for an explanation of pages. There are a number of
- escape sequences to deal with pages. Text may be copied from one page
- to another and one may move the cursor from page to page. Switching
- pages may or may not be automatic: when the screen becomes full (page
- 1) then more data from the host goes to page 2. The cursor may only
- be on one page at a time and characters which are sent to the terminal
- go there. If that page is not being displayed, new text will be
- received by the terminal and go into display memory, but you will not
- see it (until the terminal is switched to that page).
-
-
- 22.
-
- Appendix C: Serial Communications on EIA-232 (RS-232)
-
- 22.1. Intro to Serial Communication
-
- (Much of this section is now found in Serial-HOWTO.) Text terminals
- on Unix-like systems (and on PC's) are usually connected to an
- asynchronous 232 serial port of a computer. It's usually a RS-232-C,
- EIA-232-D, or EIA-232-E. These three are almost the same thing. The
- original RS prefix became EIA (Electronics Industries Association) and
- later EIA/TIA after EIA merged with TIA (Telecommunications Industries
- Association). The EIA-232 spec provides also for synchronous (sync)
- communication but the hardware to support sync is almost always
- missing on PC's. The RS designation is obsolete but is still in use.
- EIA will be used in this article.
-
- The serial port is more than just a physical connector on the back of
- a computer or terminal. It includes the associated electronics which
- must produce signals conforming to the EIA-232 specification. The
- standard connector has 25 pins, most of which are unused. An
- alternative connector has only 9 pins. One pin is used to send out
- data bytes and another to receive data bytes. Another pin is a common
- signal ground. The other "useful" pins are used mainly for signalling
- purposes with a steady negative voltage meaning "off" and a steady
- positive voltage meaning "on".
-
- The UART (Universal Asynchronous Receiver-Transmitter) chip does most
- of the work. Today, the functionality of this chip is usually built
- into another chip.
-
-
- 22.2. Voltages
-
- 22.2.1. Voltage for a bit
-
- At the EIA-232 serial port, voltages are bipolar (positive or negative
- with respect to ground) and should be about 12 volts in magnitude
- (some are 5 or 10 volts). For the transmit and receive pins +12
- volts is a 0-bit (sometimes called "space") and -12 volts is a 1-bit
- (sometimes called "mark"). This is known as inverted logic since
- normally a 0-bit is both false and negative while a one is normally
- both true and positive. Although the receive and transmit pins are
- inverted logic, other pins (modem control lines) are normal logic with
- a positive voltage being true (or "on" or "asserted") and a negative
- voltage being false (or "off" or "negated"). Zero voltage has no
- meaning (except it usually means that the PC is powered off).
-
- A range of voltages is allowed. The specs say the magnitude of a
- transmitted signal should be between 5 and 15 volts but must never
- exceed 25 V. Any voltage received under 3 V is undefined (but some
- terminals will accept a lower voltage as valid). One sometimes sees
- erroneous claims that the voltage is commonly 5 volts (or even 3
- volts) but it's usually 11-12 volts. If you are using a EIA-422 port
- on a Mac computer as an EIA-232 (requires a special cable) or EIA-423
- then the voltage will actually be only 5 V. The discussion here
- assumes 12 V. There is much confusion about voltages on the Internet.
-
- Note that normal computer logic normally is just a few volts (5 volts
- was once the standard) so that if you try to use test equipment
- designed for testing 3-5 volt computer logic (TTL) on the 12 volts of
- a serial port, it may damage the test equipment.
-
-
- 22.2.2. Voltage sequence for a byte
-
- The transmit pin (TxD) is held at -12 V (mark) at idle when nothing is
- being sent. To start a byte it jumps to +12 V (space) for the start
- bit and remains at +12 V for the duration (period) of the start bit.
- Next comes the low-order bit of the data byte. If it's a 0-bit
- nothing changes and the line remains at +12 V for another bit-period.
- Then comes the next bit, etc. Finally, a parity bit may be sent and
- then a -12 V (mark) stop bit. The line remains at -12 V (idle) until
- the next start bit. Note that there is no return to 0 volts and thus
- there is no simple way (except by a synchronizing signal) to tell
- where one bit ends and the next one begins for the case where 2
- consecutive bits are the same polarity (both zero or both one).
-
-
- A 2nd stop bit would also be -12 V, just the same as the first stop
- bit. Since there is no signal to mark the boundaries between these
- bits, the only effect of the 2nd stop bit is that the line must remain
- at -12 V idle twice as long. The receiver has no way of detecting the
- difference between a 2nd stop bit and a longer idle time between
- bytes. Thus communications works OK if one end uses one stop bit and
- the other end uses 2 stop bits, but using only one stop bit is
- obviously faster. In rare cases 1 1/2 stop bits are used. This means
- that the line is kept at -12 V for 1 1/2 time periods (like a stop bit
- 50% wider than normal).
-
-
- 22.3. Parity Explained
-
- Characters are normally transmitted with either 7 or 8 bits (of data).
- An additional parity bit may (or may not) be appended to this
- resulting in a byte length of 7, 8 or 9 bits. Some terminal emulators
- and older terminals do not allow 9 bits. Some prohibit 9 bits if 2
- stop bits are used (since this would make the total number of bits too
- large: 12 bits total).
-
- The parity may be set to odd, even or none (mark and space parity may
- be options on some terminals). With odd parity, the parity bit is
- selected so that the number of 1-bits in a byte, including the parity
- bit, is odd. If a such a byte gets corrupted by a bit being flipped,
- the result is an illegal byte of even parity. This error will be
- detected and if it's an incoming byte to the terminal an error-
- character symbol will appear on the screen. Even parity works in a
- similar manner with all legal bytes (including the parity bit) having
- an even number of 1-bits. During set-up, the number of bits per
- character usually means only the number of data bits per byte (7 for
- true ASCII and 8 for various ISO character sets).
-
- A "mark" is a 1-bit (or logic 1) and a "space" is a 0-bit (or logic
- 0). For mark parity, the parity bit is always a one-bit. For space
- parity it's always a zero-bit. Mark or space parity only wastes
- bandwidth and should be avoided when feasible. "No parity" means that
- no parity bit is added. For terminals that don't permit 9 bit bytes,
- "no parity" must be selected when using 8 bit character sets since
- there is no room for a parity bit.
-
-
- 22.4. Forming a Byte (Framing)
-
- In serial transmission of bytes via EIA-232 ports, the low-order bit
- is always sent first. Serial ports on PC's use asynchronous
- communication where there is a start bit and a stop bit to mark the
- beginning and end of a byte. This is called framing and the framed
- byte is sometimes called a frame. As a result a total of 9, 10, or 11
- bits are sent per byte with 10 being the most common. 8-N-1 means 8
- data bits, No parity, 1 stop bit. This adds up to 10 bits total when
- one counts the start bit. One stop bit is almost universally used.
- At 110 bits/sec (and sometimes at 300 bits/sec) 2 stop bits were once
- used but today the 2nd stop bit is used only in very unusual
- situations (or by mistake since it seemingly still works OK that way).
-
-
- 22.5. Limitations of EIA-232
-
- 22.5.1. Low Speed & Short Distance
-
- The conventional EIA-232 serial port is inherently low speed and is
- severely limited in distance. Ads often read "high speed" but it can
- only work at high speed over very short distances such as to a modem
- located right next to the computer. All of the wires use a common
- ground return so that twisted-pair technology (needed for high speeds)
- can't be used without additional hardware. However some computers
- have more modern interfaces. See ``Successors to EIA-232''.
-
- It is somewhat tragic that the RS-232 standard from 1969 did not use
- twisted pair technology which could operate about a hundred times
- faster. Twisted pairs have been used in telephone cables since the
- late 1800's. In 1888 (over 110 years ago) the "Cable Conference"
- reported its support of twisted-pair (for telephone systems) and
- pointed out its advantages. But over 80 years after this approval by
- the "Cable Conference", RS-232 failed to utilize it. Since RS-232
- was originally designed for connecting a terminal to a low speed modem
- located nearby, the need for high speed and longer distance
- transmission was apparently not recognized.
-
-
- 22.5.2. Successors to EIA-232
-
- See the Serial-HOWTO section "Other Serial Devices" for a longer
- discussion about non-EIA-232 ports. A number of EIA standards have
- been established for higher speeds and longer distances using twisted-
- pair (balanced) technology. Balanced transmission can sometimes be a
- hundred times faster than unbalanced EIA-232. For a given speed, the
- distance (maximum cable length) may be many times longer with twisted
- pair. Few terminals seem to support them. While many terminals also
- support EIA-423 is is almost like EIA-232 but is only 5 volts and
- somewhat higher speeds (without using twisted pair). Twisted pair
- includes EIA-422, EIA-530-A, HSSI (High Speed Serial Interface), USB
- (Universal Serial Bus), and of course ethernet.
-
-
- 22.5.3. Line Drivers
-
- For a text terminal, the EIA-232 speeds are fast enough but the usable
- cable length is often too short. Balanced technology could fix this.
- The common method of obtaining balanced communication with a text
- terminal is to install 2@ line drivers in the serial line to convert
- unbalanced to balanced (and conversely). They are a specialty item
- and are expensive if purchased new.
-
-
- 22.6. Synchronization & Synchronous
-
- 22.6.1. How "Asynchronous" is Synchronized
-
- Per EIA-232 there are only two states of the transmit (or receive)
- wire: mark (-12 V) or space (+12 V). There is no state of 0 V. Thus
- a sequence of 1-bits is transmitted by just a steady -12 V with no
- markers of any kind between bits. For the receiver to detect
- individual bits it must always have a clock signal which is in
- synchronization with the transmitter clock. Such clocks generate a
- "tick" in synchronization with each transmitted (or received) bit.
-
- For asynchronous transmission, synchronization is achieved by framing
- each byte with a start bit and a stop bit (done by hardware). The
- receiver listens on the line for a start bit and when it detects one
- it starts its clock ticking. It uses this clock tick to time the
- reading of the next 7, 8 or 9 bits. (It actually is a little more
- complex than this since several samples of a bit are often taken and
- this requires additional timing ticks.) Then the stop bit is read,
- the clock stops and the receiver waits for the next start bit. Thus
- async is actually synchronized during the reception of a single byte
- but there is no synchronization between one byte and the next byte.
-
-
-
- 22.6.2. Defining Asynchronous vs Synchronous
-
- Asynchronous (async) means "not synchronous". In practice, an async
- signal is what the async serial port sends and receives which is a
- stream of bytes each delimited by a start and stop bit. Synchronous
- (sync) is most everything else. But this doesn't explain the basic
- concepts.
-
- In theory, synchronous means that bytes are sent out at a constant
- rate one after another in step with a clock signal tick. There is
- often a separate wire or channel for sending the clock signal.
- Asynchronous bytes may be sent out erratically with various time
- intervals between bytes (like someone typing characters at a
- keyboard).
-
- There are borderline situations that need to be classified as either
- sync or async. The async serial port often sends out bytes in a
- steady stream which would make this a synchronous case but since they
- still have the start/stop bits (which makes it possible to send them
- out erratically) its called async. Another case is where data bytes
- (without any start-stop bits) are put into packets with possible
- erratic spacing between one packet and the next. This is called sync
- since the bytes within each packet must be transmitted synchronously.
-
-
- 22.6.3. Synchronous Communication
-
- Did you ever wonder what all the unused pins are for on a 25-pin
- connector for the serial port? Most of them are for use in
- synchronous communication which is seldom implemented on PC's. There
- are pins for sync timing signals as well as for a sync reverse
- channel. The EIA-232 spec provides for both sync and async but PC's
- use a UART (Universal Asynchronous Receiver/Transmitter) chip such as
- a 16450, 16550A, or 16650 and can't deal with sync. For sync one
- needs a USART chip or the equivalent where the "S" stands for
- Synchronous. Since sync is a niche market, a sync serial port is
- likely to be quite expensive.
-
- Besides the sync part of the EIA-232, there are various other EIA
- synchronous standards. For EIA-232, 3 pins of the connector are
- reserved for clock (or timing) signals. Sometimes it's a modem's task
- to generate some timing signals making it impossible to use
- synchronous communications without a synchronous modem (or without a
- device called a "synchronous modem eliminator" which provides the
- timing signals).
-
- Although few serial ports are sync, synchronous communication does
- often take place over telephone lines using modems which use V.42
- error correction. This strips off the start/stop bits and puts the
- date bytes in packets resulting in synchronous operation over the
- phone line.
-
-
- 22.7. Block Mode
-
- 22.7.1. Introduction to Block Mode
-
- Block mode is seldom used with Linux and is mainly of historical
- interest. In block mode, when one types at a terminal the results are
- saved in the terminal memory and are not sent just yet to the host
- computer. Such terminals often have built-in editing capabilities.
- When the user presses certain keys (such as the send key) what has
- been saved in the terminal memory is sent to the host computer. Now
- the Linux editors vi and emacs, must react instantly to typing certain
- keys so block mode isn't feasible. Such editors and other interactive
- programs can't permit the long delay in sending a keystroke to the
- computer which is inherent in block mode. So they can't use block
- mode.
-
- The old IBM mainframe interface uses block mode (see ``IBM Terminals
- '' so many IBM terminals are block-mode only and also synchronous (see
- Section ``Synchronization & Synchronous'').
-
-
- 22.7.2. Types of Block Modes, Forms
-
- Block mode may itself have various sub-modes such as "page" (a page at
- a time) and "line" (a line at a time). Some terminals have both block
- transmission modes and conventional character modes and may be
- switched from one mode to another. Async terminals which have block
- modes include HP2622A, Wyse60, VT130, VT131, VT330, VT340, and
- Visual500. Many later model terminals can emulate block mode. But
- the Linux console can't. Block modes may include a forms capability
- where the host computer sends a form to the terminal. Then the user
- fills it out and hits the send key which sends only the data in the
- form back to the host computer. The form itself (not the data) is
- displayed on the screen in protected fields which don't get
- transmitted to the host.
-
-
- 22.7.3. Efficiency
-
- Block mode takes load off the host computer, especially if the host
- computer's hardware is designed for block modes (as IBM mainframes
- were). In character mode every character typed is sent immediately to
- the serial port and usually causes an interrupt at the host computer.
- The host that receives the byte must stop whatever it is doing and
- fetch that character from the port hardware. Even with UART's that
- have FIFO hardware buffers, the hardware timeout is normally only the
- transmission time of 3 bytes so that an interrupt is usually issued
- for every character typed.
-
- In true block mode a long block of characters is received using only
- one interrupt. If block mode is used with conventional async FIFO
- serial ports, an interrupt is needed only every 14 bytes since they
- have 16-byte hardware buffers. Thus much of the load and overhead of
- interrupt handling is eliminated and the computer has more time to do
- other tasks when block mode is used.
-
- A significant savings for block mode occurs if the terminal is
- connected to its host via a network. Without block mode, every
- character (byte) typed is sent in its own packet including all the
- overhead bytes (40 in a TCP/IP packet as used on the Internet). With
- block mode, a large number of characters are sent in a single packet.
-
-
- 22.7.4. Problems with block mode
-
- While block mode is more efficient, it is nearly extinct, and for good
- reason. Faster and cheaper computers made the higher efficiency less
- important. For example, a 56k modem results in hundreds of interrupts
- per second (every 14 characters) while typing at a terminal only
- causes a few interrupts per second (one for each character typed). So
- the number of interrupts caused by typing at a terminal is not very
- significant (unless you have hundred of terminals connected to the
- same computer).
-
- Another point is that the efficiency is not of much significance where
- the user doesn't type in very much. Editors are a primary example of
- where the user types in a lot. But if you use block mode for
- editing, you must then use the crude editor built into terminal.
- Modern editors like vim and emacs are much better but can't use block
- mode. Even in the days of mainframes with terminals, block mode
- wasn't used much except by IBM. A major reason was that software to
- utilize it was not widely available (except for IBM). The terminfo
- data base doesn't seem to include it and this would complicate writing
- software for it.
-
-
- 22.8. EIA-232 (RS-232) Books
-
- (Note: The first book covers much more than just EIA-232.)
-
- · Black, Uyless D.: Physical Layer Interfaces & Protocols, IEEE
- Computer Society Press, Los Alamitos, CA, 1996.
-
- · Campbell, Joe: The RS-232 Solution, 2nd ed., Sybex, 1982.
-
- · Putnam, Byron W.: RS-232 Simplified, Prentice Hall, 1987.
-
- · Seyer, Martin D.: RS-232 Made Easy, 2nd ed., Prentice Hall, 1991.
-
-
- 22.9. Serial Software
-
- See Serial Software
- for Linux software for the serial ports including getty and port
- monitors.
-
-
- 23. Appendix D: Notes by Brand/Model
-
- Here are notes by brand name that were too specific to a certain
- terminal to be put elsewhere in this HOWTO. If you have some info to
- contribute on a certain terminal that is not covered elsewhere, it
- could go here. Various models often have much in common which only
- need be written about in one place. It would be nice if for each
- terminal model, there were a set of links linking to the documentation
- relevant to that model (including escape codes). But it hasn't been
- done. Note that some VT (DEC) manuals are now available on the
- Internet. See and ``VT (DEC)''. Wyse has put the information from
- its manuals on the Internet. See ``Wyse Terminals''.
-
-
- 23.1. Adds
-
- The Adds terminal menu incorrectly used "Xon/Xoff" to mean any kind of
- flow control. True for which models ??
-
- Adds, which made the Adds Viewpoint terminal, was taken over by
- Boundless Technologies.
-
-
- 23.2. CIT
-
- CIT terminals were made in Japan in the 1980's for CIE Terminals.
- They ceased to be imported in the late 1980's. The company, CIE,
- still makes CItoh printers (in 1997) but has no parts for its
- abandoned terminals. Ernie at (714) 453-9555 in Irvine CA sells (in
- 1997) some parts for models 224, 326, etc. but has nothing for the 80
- and 101.
-
- To save the Set-Up parameters press ^S when in Set-Up mode. cit80:
- Contrast: knob on rear of terminal, cit101e: Brightness: use up/down
- arrow keys in Set-Up mode.
-
-
-
- 23.3. IBM Terminals
-
- Don't confuse IBM terminals with IBM PC monitors. Many IBM terminals
- don't use ASCII but instead use an 8-bit EBCDIC code. It's claimed
- that in EBCDIC the bit order of transmission is reversed from normal
- with the high-order bit going first. The IBM mainframe communication
- standards are a type of synchronous communication in block mode (sends
- large packets of characters). Two standards are "BISYNC" and "SNA"
- (which includes networking standards). Many of their terminals
- connect with coax cable (RG62A/U) and naive persons may think the
- "BNC" connecter on the terminal is for ethernet (but it's not).
-
- While this IBM system is actually more efficient than what is
- normally used in Linux, terminals meeting this IBM standard will not
- currently work with Linux. However, some IBM terminals are
- asynchronous ASCII terminals and should work with Linux on PC's. The
- numbers 31xx may work with the exception that 317x and 319x are not
- ASCII terminals. Before getting an IBM terminal, make sure there is a
- termcap (terminfo) for it. If their isn't, it likely will not work
- with Linux. Even if there is a terminfo, it may not work. For
- example, there is a termcap for 327x but the 3270 is an EBCDIC
- synchronous terminal.
-
- The 3270 series includes the 3278 (late 1970's), 3279 with color and
- graphics, and the 3274 terminal controller (something like the 3174).
- They may be used for both BISYNC and SNA. The 3290 has a split screen
- (splits into quarters).
-
- The synchronous IBM terminals don't connect directly to the IBM
- mainframe, but connect to a "terminal controller" (sometimes called
- "cluster controller" or "communication controller"). Some of these
- controllers can convert a synchronous signal to asynchronous so that
- in this case a synchronous terminal could indirectly connect to a
- Unix-like host computer via its serial port. But there is still a
- major problem and that is block transmission. See section ``Block
- Mode''.
-
-
- 23.3.1. IBM 3153
-
- It's claimed that the Aux port is DCE and uses a straight-thru cable.
-
-
- 23.4. Teletypes
-
- These are antiques and represent the oldest terminals. They are like
- remotely controlled typewriters but are large and noisy. Made by the
- Teletype Corp., the first models were made in the 1920's and predate
- the computer by over 30 years. Early models used electro-mechanical
- relays and rotating distributors instead of electronics. Their Baudot
- code was only 5-bits per character as compared to 7-bit ASCII. See
- the book "Small Computer Systems Handbook" by Sol Libes, Hayden Books,
- 1978: pp. 138-141 ("Teletypes").
-
-
- 23.5. VT (DEC)
-
- Digital Equipment Corporation made the famous VT series of terminals
- including the commonly emulated VT100. In 1995 they sold their
- terminal business to SunRiver which is now named Boundless
- Technologies. Detailed VT terminal information, some manuals, and
- history is at . Other information is
- available at Shuford's Website
- . Information on
- current products is available from the Boundless website. See
- ``Terminal Info on the Internet''.
- VT220: Some have a BNC connector for video output (not for input).
- Sometimes people erroneously think this is for an ethernet connection.
-
- VT520: Supports full DTR/DSR flow control.
-
- Dorio: Can emulate many other terminals. The "sco unix console" is
- claimed to be a powerful emulation using the "scoansi" terminfo.
-
-
- 23.6. Links
-
- The terminal maker Links was taken over by Wyse.
-
-
- 23.7. Qume
-
- Qume was taken over by Wyse in the early 1990s.
-
-
- 23.8. Wyse Terminals
-
- For detailed manual-like information on old terminals see
- . This
- information includes specs, lists of escape sequences, part lists,
- FAQs, setup info, etc. Thanks to Wyse for providing this. For the
- specs on more recent terminals see See Wyse terminals
- .
-
- Wyse terminals were lower in cost than other brands and they captured
- a major share of the market. There were concerns about the quality of
- these terminals, especially the Wyse 50. But the large number of
- failure reports is due in part to the large number of Wyse terminals
- in use.
-
-
- 23.8.1. Wyse 50
-
- Reported not to last very long.
-
-
- 23.8.2. Wyse 60
-
- Display adjustments (must remove cover): Brightness VR202, Height
- VR302, Width VR101 (also affects height). If you want to use it in
- Native Personality, then the arrow-key codes will conflict with the
- codes used in vi (such as ^L). To fix this set "Application key mode"
- with ESC ~ 3. This results in the arrow keys sending 0xd1 - 0xd4.
- Due to a bug in the readline interface of the Bash shell, you need to
- edit /etc/inputrc so that the arrow keys will work in Bash. See
- ``Bugs in Bash''
-
-
- 23.8.3. Wyse 85
-
- Can emulate VT52/VT100/VT200. Press F3 for setup. After moving
- left/right to go the a menu "icon", press space to select it. Scroll
- thru setup menus with up/down keys. Press F3 at any time to reenter
- setup (without loosing any settings).
-
-
- 23.8.4. Wyse 99-GT
-
- Here is the setup Menus of the Wyse99GT (late 1980's). Note that TERM
- means "termination" (character) and not "terminal".
-
-
- WYSE 99-GT Terminal Set-Up as used at the University of CA, Irvine
- by David Lawyer, April 1990
-
- F1 DISP:
- COLUMNS=80 LINES=24 CELL SIZE=10 X 13
- STATUS LINE=STANDARD BACKGROUND=DARK SCROLL SPEED=JUMP
- SCREEN SAVER=OFF CURSOR=BLINK BLOCK DISPLAY CURSOR=ON
- ATTRIBUTE=CHAR END OF LINE WRAP=ON AUTO SCROLL=ON
- ----------------------------------------------------------------------------
- F2 GENERAL:
- PERSONALITY=VT 100 ENHANCE=ON FONT LOAD=OFF
- COMM MODE=FULL DUPLEX RCVD CR=CR SEND ACK=ON
- RESTORE TABS=ON ANSWERBACK MODE=OFF ANSWERBACK CONCEAL=OFF
- WIDTH CHANGE CLEAR=OFF MONITOR=OFF TEST=OFF
- ----------------------------------------------------------------------------
- F3 KEYBRD:
- KEYCLICK=OFF KEYLOCK=CAPS KEY REPEAT=ON
- RETURN=CR ENTER=CR FUNCT KEY=HOLD
- XMT LIMIT=NONE FKEY XMT LIMIT=NONE BREAK=170MS
- LANGUAGE=US MARGIN BELL=OFF PRINTER RCV=OFF
- ----------------------------------------------------------------------------
- F4 COMM:
- DATA/PRINTER=AUX/MODEM MDM RCV BAUD RATE=9600 MDM XMT BAUD RATE=9600
- MDM DATA/STOP BITS=8/1 MDM RCV HNDSHAKE=NONE MDM XMT HNDSHAKE=NONE
- MDM PARITY=NONE AUX BAUD RATE=9600 AUX DATA/STOP BITS=8/1
- AUX RCV HNDSHAKE=NONE AUX XMT HNDSHAKE=NONE AUX PARITY=NONE
- (There is a main port (Modem=MDM) and an Auxiliary Port (AUX)
- ----------------------------------------------------------------------------
- F5 MISC 1:
- WARNING BELL=ON FKEY LOCK=OFF FEATURE LOCK=ON
- KEYPAD=NUMERIC DEL=DEL/CAN XFER TERM=EOS
- CURSOR KEYS=NORMAL MARGIN CTRL=0 DEL FOR LOW Y=ON
- GIN TERM=CR CHAR MODE=MULTINATIONAL
- ----------------------------------------------------------------------------
- F6 MISC 2:
- LOCAL=OFF SEND=ALL PRINT=NATIONAL
- PORT=EIA DATA SEND AREA=SCREEN PRINT AREA=SCREEN
- DISCONNECT=60 MSEC SEND TERM=NONE PRINT TERM=NONE
- PRINT MODE=NORMAL VT100 ID=VT100 POUND=US
- ----------------------------------------------------------------------------
- F7 TABS: You should see several "T" characters spaced 8 dots apart.
- If you don't, hit backspace.
- F8 F/KEYS: Normally you will see no definitions for the Function Keys
- here (unless someone has set them up and saved them). This means that
- they will normally generate their default settings (not displayed here).
- shows the "user defined definition" of the F5 key, etc.
- F9 A/BACK: Normally not defined: ANSWERBACK =
- F10 EXIT: Selecting "DEFAULT ALL" will make the factory default settings
- the default.
-
-
-
- HINTS on use of WY-99GT User's Guide: Note that much that is missing
- from this Guide may be found in the WY-99GT Programmer's Guide. The
- VT100 emulation (personality) is known as ANSI and uses ANSI key codes
- per p. A-10+ even though the keyboard may be ASCII. A sub-heading on
- p. A-13 "ASCII Keyboard" also pertains to VT100 because it has an
- "ANSI KEY ..." super-heading a few pages previously. But not all
- ASCII keyboard headings pertain to VT100 since they may fall under a
- non-ANSI personality super-heading which may found be a few pages
- previously. Appendix H is the "ANSI Command Guide" except for the
- VT52 (ANSI) personality which is found in Appendix G.
-
-
-
- 23.8.5. Wyse 150
-
- When exiting set-up using F12, hitting space changes "no" to "yes" to
- save the set-up. The sentence to the left of this no/yes is about
- "vertical alignment" and has nothing to do with this no/yes for saving
- the set-up (confusing menu design).
-
- END OF Text-Terminal-HOWTO
-
-
-
diff --git a/LDP/guide/docbook/Linux-Networking/Thin-Client.xml b/LDP/guide/docbook/Linux-Networking/Thin-Client.xml
deleted file mode 100644
index dd44b3a3..00000000
--- a/LDP/guide/docbook/Linux-Networking/Thin-Client.xml
+++ /dev/null
@@ -1,5942 +0,0 @@
- NFS-Root mini-HOWTO
- not maintained
- V9, 20 September 2002
-
- This mini-HOWTO tries explains how to set up a ``diskless'' Linux
- workstation, which mounts its root filesystems via NFS. The newest
- version of this mini-HOWTO can always be found at
- http://www.tldp.org/HOWTO/mini/NFS-Root.html
- or a Linux Documenta
- tion Project mirror NEAR YOU.
- ______________________________________________________________________
-
- Table of Contents
-
-
- 1. Copyright
-
- 1.1 Contributors
-
- 2. General Overview
-
- 3. Setup on the server
-
- 3.1 Compiling the kernels
- 3.2 Creation of the root filesystem
- 3.2.1 Copying the filesystem
- 3.2.2 Changes to the root filesystem
- 3.2.3 Exporting the filesystem
- 3.2.4 RARP setup
- 3.2.5 BOOTP setup
- 3.2.6 DHCP setup
- 3.2.7 Finding out hardware addresses
-
- 4. Booting the workstation
-
- 4.1 Using a boot ROM
- 4.2 Using a raw kernel disk
- 4.3 Using a bootloader &
- 4.4 Using a bootloader without
- 4.5 Sample kernel command lines
-
- 5. Known problems
-
- 5.1 /sbin/init doesn't start.
- 5.2 /dev troubles.
-
- 6. Other resources
-
-
-
- ______________________________________________________________________
-
- 1. Copyright
-
- (c) 1996 Andreas Kostyrka (e9207884@student.tuwien.ac.at or
- andreas@ag.or.at)
-
-
- Unless otherwise stated, Linux HOWTO documents are copyrighted by
- their respective authors. Linux HOWTO documents may be reproduced and
- distributed in whole or in part, in any medium physical or electronic,
- as long as this copyright notice is retained on all copies. Commercial
- redistribution is allowed and encouraged; however, the author would
- like to be notified of any such distributions.
-
-
- All translations, derivative works, or aggregate works incorporating
- any Linux HOWTO documents must be covered under this copyright notice.
- That is, you may not produce a derivative work from a HOWTO and impose
- additional restrictions on its distribution. Exceptions to these rules
- may be granted under certain conditions; please contact the Linux
- HOWTO coordinator at the address given below.
-
- In short, we wish to promote dissemination of this information through
- as many channels as possible. However, we do wish to retain copyright
- on the HOWTO documents, and would like to be notified of any plans to
- redistribute the HOWTOs.
-
- If you have questions, please contact Andreas Kostyrka
- , the author of this mini-HOWTO, or the Linux
- HOWTO coordinator, at via email.
-
-
- 1.1. Contributors
-
-
- · Avery Pennarun (how to boot without LILO)
-
- · Ofer Maor (a better mini-HOWTO about setting
- up diskless workstations)
-
- · Christian Leutloff (info about
- netboot)
-
- · Greg Roelofs (2.2/2.4 updates, DHCP info, NFS-
- export info)
-
-
- 2. General Overview
-
- An NFS-mounted root filesystem is typically most useful in two
- situations:
-
- · A system administrator may wish to aggregate storage for multiple
- workstations in order to simplify maintenance, improve security and
- reliability, and/or make more economical use of limited storage
- capacity. In this scenario, a single, large server may host a
- dozen or more workstations; all of the systems can be regularly
- backed up from a central location, and individual clients are less
- prone to damage by unsophisticated users or attack by malicious
- parties with physical access. (Of course, if the server itself is
- compromised, then so are all of the clients.)
-
- · An embedded system may not have a disk, an IDE interface, or even a
- PCI bus. Even if it does, during development it may be too
- unstable to use the disk, and a ramdisk may be too small to include
- all of the necessary utilities or too large (as a part of the
- kernel image) to allow for rapid turnaround during testing and
- development. An NFS root allows quick kernel downloads, helps
- ensure filesystem integrity (since the server is basically
- impervious to crashes by the client), and provides virtually
- infinite storage.
-
- (In this document we'll use the terms client and workstation
- interchangeably.)
-
-
- However, there are two small problems from the client's perspective:
-
- · It must find out its own IP address and possibly also the rest of
- the ethernet configuration (gateway, netmask, name servers, etc.).
-
- · It must know or discover both the IP address of the NFS server and
- the mount path (on the server) to the exported root filesystem.
-
-
- The current implementation of NFSROOT in the Linux kernel (as of
- 2.4.x) allows for several approaches, including:
-
- · The complete ethernet configuration, including the NFS-path to be
- mounted, may be passed as parameters to the kernel via LILO,
- LOADLIN, or a hard-coded string within
- linux/arch/i386/kernel/setup.c (or its equivalent for other
- architectures).
-
- · The IP address may be discovered by RARP and the NFS-path passed
- via kernel parameters.
-
- · The IP address may be discovered by RARP, with the NFS-path derived
- from the RARP server and the just-granted IP address (loosely
- speaking, ``mount -t nfs :/tftpboot//dev/nfs'').
-
- · The client configuration may be discovered by BOOTP.
-
- · The client configuration may be discovered by DHCP.
-
- Since the most common dynamic-address protocol these days is DHCP, its
- addition as an option in kernels 2.2.19 and 2.4.x (3 < x <= 14) is
- particularly welcome.
-
- Before starting to set up a diskless environment, you should decide if
- you will be booting via LILO, LOADLIN, or a custom, embedded
- bootloader. The advantage of using something like LILO is flexibility;
- the disadvantage is speed--booting a Linux kernel without LILO is
- faster. This may or may not be a consideration.
-
-
- 3. Setup on the server
-
- 3.1. Compiling the kernels
-
- On the server side, if you don't plan to use the old, user-mode NFS
- daemon, you'll need to compile NFS server support into the kernel
- (``NFS server support,'' a.k.a. knfsd or CONFIG_NFSD). If you plan to
- use the older RARP protocol to assign the client an IP address, RARP
- support in the kernel of the server is probably a good idea. (You must
- have it if you will boot via RARP without kernel parameters.) On the
- other hand, it doesn't help you if the client isn't on the same subnet
- as the server.
-
-
- The kernel for the workstation needs the following settings, as a
- minimum:
-
- · NFS filesystem support (CONFIG_NFS_FS). Note that there is no need
- for ext2 support.
-
- · Root file system on NFS (CONFIG_ROOT_NFS).
-
- · Ethernet (10 or 100Mbit) (CONFIG_NET_ETHERNET).
-
- · The ethernet driver for the workstation's network card (or onboard
- ethernet chip, if it's built into the motherboard or chipset).
-
- Where there is an option to compile something in as a module, do
- not do so; modules only work after the kernel is booted, and these
- things are needed during boot.
- For dynamically assigned IP numbers, you'll also need to select one or
- more of these kernel options:
-
- · IP: kernel level autoconfiguration (CONFIG_IP_PNP)
-
- · RARP support (CONFIG_IP_PNP_RARP)
-
- · BOOTP support (CONFIG_IP_PNP_BOOTP)
-
- · DHCP support (CONFIG_IP_PNP_DHCP)
-
-
- If the workstation will be booted without kernel parameters, you need
- also to set the root device to 0:255. Do this by creating a dummy
- device file with mknod /dev/nfsroot b 0 255. After having created such
- a device file, you can set root device of the kernel image with rdev
- /dev/nfsroot. [NOTE: Modern kernels recognize
- root=/dev/nfs as a command-line argument; for consistency and/or
- compatibility, it may be better to use /dev/nfs as the device name
- instead of /dev/nfsroot.]
-
-
- 3.2. Creation of the root filesystem
-
- 3.2.1. Copying the filesystem
-
- Warning: while these instruction might work for you, they are by no
- means sensefull in a production environment. For a better way to set
- up a root filesystem for the clients, see the NFS-Root-Client mini-
- HOWTO by Ofer Maor .
-
-
- After having decided where to place the root tree, create it with
- (e.g.) mkdir -p and tar cClf / - | tar xpCf -.
-
-
- If you boot your kernel without LILO, then the rootdir has to be
- /tftpboot/. If you don't like it, you can change it in the
- top Makefile in the kernel sources, look for a line like: NFS_ROOT =
- -DNFS_ROOT="\"/tftpboot/%s\"" If you change this, you have to
- recompile the kernel.
-
-
-
- 3.2.2. Changes to the root filesystem
-
- Now trim the unneeded files, and check the /etc/rc.d scripts. Some
- important points:
-
- · One important thing is eth0 setup. The workstation comes up with
- eth0 set up, at least partially. Setting the IP address of the
- workstation to the the IP address of the server is not considered a
- clever thing to do. (As it happened to the original author on one
- of his early attempts.)
-
- · Another point is the /etc/fstab of the workstation. It should be
- set up for NFS filesystems.
-
- · WARNING: Don't confuse the server root filesystem and the
- workstation root filesystem. (I've already patched up a rc.inet1 on
- the server, and wondered why the workstation still didn't work.)
-
-
- 3.2.3. Exporting the filesystem
-
- Export the root dir to the workstation. The basic idea is to edit
- /etc/exports to include a line similar to one of the following:
-
-
-
- · /path/on/server/to/nfs_root (rw,no_root_squash,no_all_squash) <2nd-client-IP-
- number>(rw,no_root_squash,no_all_squash)
-
- · /path/on/server/to/nfs_root /(rw,no_root_squash,no_all_squash)
-
-
- For example, a DHCP client receiving an IP address on a class C subnet
- would need an exports entry similar to this:
-
-
-
- · /path/on/server/to/nfs_root
- 192.168.263.0/255.255.255.0(rw,no_root_squash,no_all_squash)
-
-
- The no_root_squash parameter allows the superuser (root) to be treated
- as such by the NFS server; otherwise root will be remapped to nobody
- and will generally be unable to do anything useful with the
- filesystem. The no_all_squash parameter is similar but applies to
- non-root users. See the exports(5) man page for details.
-
-
- You will have to notify the NFS server after making any changes to the
- exports file. Under Red Hat this can easily be done by typing
- /etc/rc.d/init.d/nfs stop; /etc/rc.d/init.d/nfs start. On other
- systems, a simple /etc/rc.d/init.d/nfs restart or even exportfs -a may
- suffice, while on older machines running the user-mode NFS daemon you
- may actually need to killall -HUP rpc.mountd; killall -HUP rpc.nfsd.
- (Do not killall -HUP rpc.portmap, however!)
-
-
- You may also need to edit /etc/hosts.allow and/or /etc/hosts.deny if
- tcp_wrappers are installed. In particular, if the remote system
- (client) gets RPC: connection refused errors, /etc/hosts.deny probably
- contains portmap: ALL or ALL: ALL. To enable the client to use the
- server's portmapper, add a corresponding line to /etc/hosts.allow:
-
-
- portmap:
- portmap: <2nd-client-IP-number>
- portmap: /
-
-
-
- There is no need to restart anything in this case. You can check by
- running rpcinfo -p on the NFS server and rpcinfo -p NFS-server on a
- Linux client within the allowed range; the RPC services listed by both
- should match.
-
-
- In case of problems, check /var/log/messages and /var/log/syslog for
- errors (for example, run tail -f /var/log/messages /var/log/syslog and
- then try booting the client), and check your man pages (exports,
- exportfs, portmap, etc.). As a last resort, a reboot of the NFS
- server may help, but that's a borderline Microsoftism...
- 3.2.4. RARP setup
-
- Set up the RARP somewhere on the net. If you boot without a nfsroot
- parameter, the RARP server has to be the NFS server. Usually this will
- be the NFS server. To do this, you will need to run a kernel with RARP
- support.
-
-
- To do this, execute (and install it somewhere in /etc/rc.d of the
- server!):
-
-
- /sbin/rarp -s
-
-
- where
-
- ip-addr
- is the IP address of the workstation, and
-
- hardware-addr
- is the ethernet address of the network card of the workstation.
-
-
- example: /sbin/rarp -s 131.131.90.200 00:00:c0:47:10:12
-
-
- You can also use a symbolic name instead of the IP address, as long
- the server is able to find out the IP address. (/etc/hosts or DNS
- lookups)
-
-
- 3.2.5. BOOTP setup
-
- For BOOTP setup you need to edit /etc/bootptab. Please consult the
- bootpd(8) and bootptab(5) man pages.
-
-
- 3.2.6. DHCP setup
-
- There is no need for the DHCP server to be the same as the NFS server,
- and in most cases, a DHCP server will already be set up. If one is
- not, however, consult the DHCP mini-HOWTO for further help.
-
-
- 3.2.7. Finding out hardware addresses
-
- I don't know the hardware address! How can I find it out?
-
- · Boot the kernel disk you made, and watch for the line where the
- network card is recognized. It usually contains 6 hex bytes, that
- should be the address of the card.
-
- · Boot the workstation with some OS with TCP/IP networking enabled.
- Then ping the workstation from the server. Look in the ARP-cache by
- executing: /sbin/arp -a
-
-
- 4. Booting the workstation
-
-
- 4.1. Using a boot ROM
-
- As I have not used such a beast myself yet, I can give you only the
- following tips (courtesy of Christian Leutloff
- ):
- · You can't use ``normal'' boot ROMs.
-
- · There is a netboot packet by Gero Kuhlmann, that provides for boot
- ROMs for Linux, and further information. netboot is available from
- the local Linux mirror, or as a Debian package (netboot-0.4).
-
- · Read the documentation coming with your boot ROM carefully.
-
- · You probably will have to enable the tftpd on the server, but this
- depends upon your boot ROM's way of loading the kernel.
-
- · Any information on boot-ROM vendors of these Linux variety,
- mentioned above, as not everybody has access to PROM burner :(
- (especially in Europe, as I'm located there.) welcome, I'll include
- them then here.
-
- 4.2. Using a raw kernel disk
-
- If you have exported the root filesystem with the correct name for the
- default naming and your NFS server is also the RARP server (which
- implies that the boxes are on the same subnet.), than you can just
- boot the kernel by cating it to a disk. (You have to set the root
- device in the kernel to 0:255.) This assumes, that the root directory
- on the server is /tftpboot/IP Address (this value can be changed when
- compiling the kernel.)
-
- 4.3. Using a bootloader & RARP
-
- Give the kernel all needed parameters when booting, and add
- nfsroot=: where server-ip-addr is the
- IP address of your NFS-server, and /path/to/mount is the path to the
- root directory.
-
- Tips:
-
- · When using LILO consider using the ``lock'' feature: Simply type in
- once all the correct parameters and add ``lock''. Next time when
- booting let LILO timeout.
-
- · When generating a workstation specific boot disk, you can also use
- the append= feature in lilo.conf.
-
-
- 4.4. Using a bootloader without RARP
-
- The ip and nfsroot kernel parameters (which can be hardcoded into the
- kernel, interactively entered at some bootloader prompts, or included
- in lilo.conf via the append= parameter; see the next subsection)
- provide all of the information necessary for the client to set up its
- ethernet interface and to contact the NFS server, respectively. The
- parameters are fully documented in Documentation/nfsroot.txt, which is
- included in the kernel sources (usually found under /usr/src/linux).
- Here's the format for a machine with a static (pre-assigned) IP
- address:
-
-
-
- · nfsroot=:/path/on/server/to/nfs_root
- ip=:::::eth0:off
-
-
- DHCP is much simpler:
-
-
-
- · nfsroot=:/path/on/server/to/nfs_root ip=dhcp
-
-
- 4.5. Sample kernel command lines
-
- Here's an example of a complete kernel command line such as you might
- include in lilo.conf or equivalent; only the IP numbers and NFS path
- are bogus:
-
-
-
- · root=/dev/nfs rw nfsroot=12.345.67.89:/path/on/server/to/nfs_root
- ip=dhcp console=ttyS1
-
-
- That uses DHCP to assign an IP address to the machine and puts its
- boot messages (console) on the second serial port. The following is
- the corresponding example using a static IP address; it also
- explicitly specifies Busybox's (non-standard) location for init:
-
-
-
- · root=/dev/nfs rw nfsroot=12.345.67.89:/path/on/server/to/nfs_root
- ip=12.345.67.88::12.345.67.1:255.255.255.0:embed-o-matic:eth0:off
- console=ttyS1 init=/bin/init
-
-
- 5. Known problems
-
-
- 5.1. /sbin/init doesn't start.
-
- A common problem with /sbin/init is that some distributions (e.g., Red
- Hat Linux) come with /sbin/init dynamically linked. So you have to
- provide a correct /lib setup to the client. An easy thing one could
- try is replacing /sbin/init (for the client) with a statically linked
- ``Hello World'' program. This way you know if it is something more
- basic, or ``just'' a problem with dynamic linking.
-
-
- Also note that Busybox by default installs its init symlink in /bin
- rather than /sbin. You may need to move it or pass an explicit init=
- parameter on the kernel command line, as shown in the final example of
- the previous section.
-
-
- 5.2. /dev troubles.
-
- If you get some garbled messages about ttys when booting, then you
- should run a MAKEDEV from the client in the /dev directory. There are
- rumors that this doesn't work with certain server OSes that use 64-bit
- device numbers; should you run into this, please consider updating
- this section! A potential solution would be to create a small /dev
- ram disk early in the boot process and reinstall the device nodes each
- time, or simply embed directly into the kernel a suitably initialized
- ramdisk.
-
-
- 6. Other resources
-
-
- · In the Documentation directory of kernel source there is a file
- documenting NFS-Root systems (Documentation/nfsroot.txt).
-
-
-
- · There are quite a few related HOWTOs:
-
- · Diskless-HOWTO (specifically, the Network Booting section)
-
- · Diskless-root-NFS-HOWTO
-
- · Diskless-root-NFS-other-HOWTO
-
- · Network-boot-HOWTO
-
- · PXE-Server-HOWTO ("Pre-boot eXecution Environment") < coming >
-
-
-
- · There is a BOOTP client:
- http://ibiblio.org/pub/Linux/system/network/admin/bootpc-0.64.tar.gz
-
-
-
- With initrd (which is included in Linux 2.0), it could be made to
- work for diskless stations quite nicely. initrd is actually always
- an advanced option for more customized setups.
-
-
- · For plain bootpd-based boots this is actually probably not needed
- as Linux 2.0 contains also the option to use BOOTP instead of RARP.
- (To be more precise, you can compile both in the kernel, and the
- faster response wins.)
-
-
-
- · There is a patch floating around that allows for swapping over NFS.
- It was sent to me (during a private high workload phase), but I
- somehow managed to lose the mail.
-
-
- You can probably get it from http://www.linuxhq.com/
- in the unofficial-patches section.
-
-NFS-Root-Client Mini-HOWTO
-
-Ofer Maor
-
- v4.1, 02 Feb, 1999
- Revision History
- Revision 4.1 Feb 02, 1999 Revised by: mo
-
- The purpose of this Mini-Howto is to explain how to create client root
- directories on a server that is using NFS Root mounted clients.
- _________________________________________________________________
-
- Table of Contents
- 1. [1]Copyright
-
- 1.1. [2]Thanks
-
- 2. [3]Preface
-
- 2.1. [4]General Overview
-
- 3. [5]Creating the client's root directory
-
- 3.1. [6]Creating the directory tree
- 3.2. [7]Creating the minimal file system needed for boot
- 3.3. [8]Building the etc directory and configuring the clients
- 3.4. [9]Booting Up
-
- 4. [10]Creating more clients
-
-1. Copyright
-
- (c) 1996 Ofer Maor (<[11]oferm@hcs.co.il>)
-
- Unless otherwise stated, Linux HOWTO documents are copyrighted by
- their respective authors. Linux HOWTO documents may be reproduced and
- distributed in whole or in part, in any medium physical or electronic,
- as long as this copyright notice is retained on all copies. Commercial
- redistribution is allowed and encouraged; however, the author would
- like to be notified of any such distributions.
-
- All translations, derivative works, or aggregate works incorporating
- any Linux HOWTO documents must be covered under this copyright notice.
- That is, you may not produce a derivative work from a HOWTO and impose
- additional restrictions on its distribution. Exceptions to these rules
- may be granted under certain conditions; please contact the Linux
- HOWTO coordinator at the address given below.
-
- In short, we wish to promote dissemination of this information through
- as many channels as possible. However, we do wish to retain copyright
- on the HOWTO documents, and would like to be notified of any plans to
- redistribute the HOWTOs.
-
- If you have questions, please contact Ofer Maor
- (<[12]oferm@hcs.co.il>), the author of this mini-HOWTO, or Greg
- Hankins, the Linux HOWTO coordinator, at <[13]gregh@sunsite.unc.edu>
- via email, or at +1 404 853 9989.
-
- If you have anything to add to this Mini-Howto, please mail the author
- (Ofer Maor, <[14]oferm@hcs.co.il>), with the information. Any new
- relevant information would be appreciated.
- _________________________________________________________________
-
-1.1. Thanks
-
- I would like to express my thanks to the author of the NFS-Root Howto,
- Andreas Kostyrca (<[15]andreas@medman.ag.or.at>). His Mini-Howto
- helped me with the first steps in creating a NFS Root Mounted client.
- My Mini-Howto does not, in any way, try to replace his work, but to
- enhance it using my experiences in this process.
-
- I would also like to thank Mark Kushinsky (<[16]mark026@ibm.net>) for
- polishing the english and spelling of this Howto, thus making it much
- more readable.
- _________________________________________________________________
-
-2. Preface
-
- This Mini-Howto was written in order to help people who want to use
- NFS Root mounting to create their client's directories. Please note
- that there are many ways to accomplish this, depending on your needs
- and intent. If the clients are individual, and each client has its own
- users and administrator, it will be necessary to make significant
- parts of the client dirs not shared with other clients. On the other
- hand, if the client is intended for multiple users, and are all
- administrated by the same person (for instance, a computerclass), make
- as many files as possible shareable in order to make administration
- more manageable. This Howto will focus on the second issue.
- _________________________________________________________________
-
-2.1. General Overview
-
- When building a client's root directory, and trying to limit ourselves
- to the minimum client size, we mainly focus on which files we can
- share, or mount from the server. In this Howto I will recommend the
- configuration of a client based on my experience. But beforewe begin
- please note:
-
- * This Mini-Howto does not explain how to do the actual NFS Root
- mounting. Refer to the NFS-Root Mini-Howto if you need more
- information about that issue.
- * I based most of my client's configuration on mounts and symbolic
- links. A lot of those symbolic links can be replaced by hardlinks.
- One should choose according to his personal preference. Putting a
- hardlink over a mount and a symbolic link has its advantages, but
- might cause confusion. A file will not be erased until all its
- hardlinks are removed. Thus, In order to prevent a case in which
- you upgrade a certain file, and the hardlinks still refer to the
- older version, you will have to be very careful and keep track of
- every link you put.
- * While mounting the information from the server, two concepts can
- be used. The first (most common) concept, is to mount the whole
- server root directory under a local directory, and then just
- change the path or link the relevant directories there. I
- personally dislike mounting root partitions of a server on
- clients. Thus, this Howto suggests a way to mount the relevant
- directories of the server to the relevant places on the system.
- * This Howto is based on my experience building client directories
- on a Slackware 3.1 based distribution. Things may be different
- (especially on the rc.* files), for other users, however the
- concepts should still remain the same.
- _________________________________________________________________
-
-3. Creating the client's root directory
-
-3.1. Creating the directory tree
-
- First of all, you need to create the directory structure itself. I
- created all the clients under /clients/hostname and I will use it for
- my examples listed below. This, however, can be changed to anything
- else. The first stage, then, is to create the relevant directories in
- the root directory. You should create the following directories:
-
- bin , dev , etc , home , lib , mnt , proc , sbin , server , tmp , usr
- , var
-
- and any other directories you might want to have on your system.
-
- The local, proc, and dev directories will be used separately on each
- machine while the rest of the directories will be either partly or
- completely shared with the rest of the clients.
- _________________________________________________________________
-
-3.2. Creating the minimal file system needed for boot
-
-3.2.1. Creating the dev dir.
-
- Although the dev dir can be shared, it is better to create a separate
- one for each client. You can create your client's dev directory with
- the appropriate MAKEDEV scripts, however in most cases it is simpler
- just to copy it from the server:
-bash# cp -a /dev /clients/hostname
-
- You should keep in mind that /dev/mouse, /dev/cdrom and /dev/modem are
- symbolic links to actually devices, and therefore you should be sure
- that they are linked correctly to fit the client's hardware.
- _________________________________________________________________
-
-3.2.2. Copying the necessary binaries.
-
- Although we mount everything from the server, there is a minimum that
- we need to copy to each client. First of all, we need "init", our
- system will not be able to run anything before init'ing (as the author
- found out in the hard way ;-). So first, you should copy /sbin/init to
- your client's sbin dir and then so that rc.S will run, you should copy
- /bin/sh to the client's bin directory. Also, in order to mount
- everything you need to copy /sbin/mount to the client's sbin
- directory. This is the minimum, assuming the first line in your rc.S
- is mount -av. However, I recommend copying a few more files: update,
- ls, rm, cp and umount, so that you will have the basic tools in case
- the client has problems mounting. If you choose to leave your swap on
- line before mount, you should also copy the swapon binary.
-
- Since most of these binaries are by default dynamically linked, you
- will also need to copy a fair part of /lib:
-bash# cp -a /lib/ld* /lib/libc.* /lib/libcursses.* /client/hostname/lib
-
- Hardlinking the binaries themselves, instead of copying them, should
- be considered. Please read my comments on this in [17]Section 2.1 of
- this Howto.
-
- Please notice, all of the information above assumes that the kernel
- has been given the network parameters while booting up. If you plan to
- use rarp or bootp, you will probably need the relevant binaries for
- these as well.
-
- Generally, you will need the minimum of files that will enable you to
- configure the network and run rc.S up to the point where it mounts the
- rest of the file system. Make sure you looked into your /etc/init and
- rc.S files, making sure there are no "surprises" in any of them, which
- will require other files to be accessed, before the first mount will
- take place. If you do, however, find such files, you can either copy
- them as well, or remove the relevant parts from your init and your
- rc.S files.
- _________________________________________________________________
-
-3.2.3. The var directory
-
- The var directory, in most cases, should be separate for each client.
- However, a lot of the data can be shared. Create under the server
- directory a directory called var. We will mount the server's var
- directory there. To create the local var directory, simply type:
-bash# cp -a /var /clients/hostname/
-
- Now, you have a choice as to what you want to separate, and what you
- want to share. Any directory/file that you want to share, simply
- remove it from the client's var dir, and symlink it to the
- /server/var/ directory. However please note that you should either
- symlink it to /server/var or to ../server/var but NOT to
- /clients/hostname/server/var as this will not work when the root
- changes.
-
- Generally, I would recommend separating /var/run, /var/lock,
- /var/spool, and /var/log.
- _________________________________________________________________
-
-3.2.4. The rest of the directories
-
- * etc is explained thoroughly in the next section.
- * mnt and proc are for local purposes.
- * usr and home are merely mount points.
- * tmp is up to you. You can create a different tmp directory for
- each client, or create some /clients/tmp directories, and mount it
- for each client under /tmp. I would recommend that you provide
- each client with a separate tmp directory.
- _________________________________________________________________
-
-3.3. Building the etc directory and configuring the clients
-
- Please Note -
-
- Note: this section refers to building the etc directory which is
- mostly shared among the clients. If your diskless clients have
- separate system administrators, it's best to set up for each client
- a separate etc directory.
- _________________________________________________________________
-
-3.3.1. Building a clients wide etc directory
- _________________________________________________________________
-
-3.3.2. Creating a client's etc directory
-
- Although we separate the etc directories of the clients, we still want
- to share a large portion of the files there. Generally, I think
- sharing the etc files with the server's /etc is a bad idea, and
- therefore I recommend creating a /clients/etc directory, which will
- hold the information needed for the clients. To start with, simply
- copy the contents of the server's etc to the /clients/etc directory.
-
- You should add to this directory all of the non-machine-specific
- configuration files, for instance motd, issue, etc. and not the
- clientspecific ones.(i.e. inittab or fstab)
-
- The most important changes will be in your rc.d directory. First, you
- should change rc.inet1 to be suitable for your local setup. I pass all
- my network parameters to the kernel through the LILO/Loadlin,
- therefore I remove almost everything from rc.inet1 file. The only
- thing I leave there is the ifconfig and route of the localhost. If you
- use rarp or bootp, you will have to build it accordingly.
-
- Secondly, you should edit your rc.S. First, remove all the parts that
- are responsible for the fsck check as fsck will occur when the server
- boots up. Then, you should find the line that mounts your fstab. This
- should look something like:
-
- mount -avt nonfs
-
- The -t nonfs is there since normal clients first run rc.S and only
- later on use rc.inet1 to configure the Ethernet. As this will cause no
- NFS partitions to be mounted this line should be deleted. Therefore,
- change it to mount -av. If you need to run rarp/bootp to configure
- your network, do it in rc.S (or call the appropriate script from
- rc.S), before the mount, and make sure your physical bin and sbin
- directories have the necessary files available.
-
- After the mount -av is performed, you will have a working file system.
- Build a general fstab, so that you can later copy it to each client.
- Your fstab should look something like this:
-
- Table 1. fstab
- server:/clients/hostname / nfs default 1 1
- server:/bin /bin nfs default 1 1
- server:/usr /usr nfs default 1 1
- server:/sbin /sbin nfs default 1 1
- erver:/home /home nfs default 1 1
- server:/lib /lib nfs default 1 1
- server:/clients/etc /server/etc nfs default 1 1
- server:/clients/var /server/var nfs default 1 1
- none /proc proc default 1 1
-
- Please notice, that the keyword default might not work on all versions
- of mount. You might change it to rw or ro or remove all of the default
- 1 1 part.
-
- Also, make sure your server's /etc/exports looks like this:
-
- Table 2. /etc/exports
- /clients/hostname hostname.domainname(rw,no_root_squash)
- /clients/etc hostname.domainname(ro,no_root_squash)
- /clients/var hostname.domainname(ro,no_root_squash)
- /usr hostname.domainname(ro,no_root_squash)
- /sbin hostname.domainname(ro,no_root_squash)
- /bin hostname.domainname(ro,no_root_squash)
- /lib hostname.domainname(ro,no_root_squash)
- /home hostname.domainname(rw,no_root_squash)
-
- Other than the first line, which should be separate for each host, the
- rest of the lines can be replaced with a hostmask to fit all your
- hosts (like pc*.domain - keep in mind though, that * will substitue
- only strings without a dot in them). I suggest that you make most of
- the directories read only, but this is up to you. The no_root_squash
- will make sure root users on the clients have actual root permissions
- on the nfsd as well. Check out man exports(5). If you want users to be
- able to run passwd from the clients also, make sure the /etc has rw
- and not ro permissions. However, this is not advisable.
-
- Please note another thing concerning the rc.S file. In Slackware, by
- default, it creates a new /etc/issue and /etc/motd every time it runs.
- This function MUST be disabled if these files are mounted ro from the
- server, and I would recommend that they should be disabled in any
- case.
-
- Lastly, if you want to have the same userbase on the server as on the
- clients, you should choose between 1), using NIS (Yellow Pages - check
- the yp-howto), and then each client will have a separate /etc/passwd
- and /etc/group as it receives it from the NIS server. 2) In most
- cases, a simple symbolic link will suffice. Therefore, you will need
- to either hardlink /clients/etc/passwd to /etc/passwd, or if you
- prefer a symlink, link /etc/passwd to /clients/etc/passwd (and not the
- other way around, since the clients do not mount the server's etc
- directory). Do the same for /etc/group.
- _________________________________________________________________
-
-3.3.3. Creating a client's etc directory
-
- Generally, most of the files in the client's etc should be symlinked
- to the /server/etc directory. However, some files are different for
- each machine, and some just have to be there when the kernel loads.
- The minimum you need from the etc dir is as follows:
-
- resolv.conf
- hosts
- inittab
- rc.d/rc.S
- fstab
-
- Since these 5 files can be identical on all clients, you can simply
- hardlink them or copy them again. However, with the rc.S and fstab
- file it is advised to keep a separate copy for each client. You will
- also need a separate etc/HOSTNAME for each client. I personally
- recommend having all of the rc.d files separate for each client, as
- configuration and hardware might vary from one to another.
-
- For each client, add to the fstab the proper swap line:
-
- Table 3. fstab
- /dev/swap_partition swap swap default 1 1
-
- The rest of the /etc files of the client, you can either hardlink to
- the /clients/etc/* files, or symlink them to the /server/etc (which is
- the mount point of /clients/etc/).
-
- Make sure your machine can resolve properly, either through a named or
- through etc/hosts. It is not a bad idea to keep the server's IP in the
- etc/hosts, instead of counting on resolving. If you will count only on
- named resolving, a problem in the named will prevent your clients from
- booting up.
- _________________________________________________________________
-
-3.4. Booting Up
-
- Now, all you have to do is to boot up your machine, cross your fingers
- and hope everything works as it should :-).
- _________________________________________________________________
-
-4. Creating more clients
-
- If you have followed my instructions so far this should be simple - cd
- to /clients/ and type:
-bash# cp -a hostname1 hostname2
-
- and then make sure you check these points:
-
- * rc.d/* files matches the hardware and wanted software
- configuration
- * etc/HOSTNAME is correct
- * fstab's swap line is correct
- * the symbolic links of dev/mouse, dev/modem and dev/cdromare right.
-
- Good Luck....
-
-References
-
- 1. file://localhost/export/sunsite/users/gferg/howto/00_NFS-Root-Client-mini-HOWTO.html#COPYRIGHT
- 2. file://localhost/export/sunsite/users/gferg/howto/00_NFS-Root-Client-mini-HOWTO.html#AEN28
- 3. file://localhost/export/sunsite/users/gferg/howto/00_NFS-Root-Client-mini-HOWTO.html#PREFACE
- 4. file://localhost/export/sunsite/users/gferg/howto/00_NFS-Root-Client-mini-HOWTO.html#OVERVIEW
- 5. file://localhost/export/sunsite/users/gferg/howto/00_NFS-Root-Client-mini-HOWTO.html#CLIENTROOT
- 6. file://localhost/export/sunsite/users/gferg/howto/00_NFS-Root-Client-mini-HOWTO.html#AEN52
- 7. file://localhost/export/sunsite/users/gferg/howto/00_NFS-Root-Client-mini-HOWTO.html#AEN74
- 8. file://localhost/export/sunsite/users/gferg/howto/00_NFS-Root-Client-mini-HOWTO.html#AEN158
- 9. file://localhost/export/sunsite/users/gferg/howto/00_NFS-Root-Client-mini-HOWTO.html#AEN371
- 10. file://localhost/export/sunsite/users/gferg/howto/00_NFS-Root-Client-mini-HOWTO.html#MORECLIENTS
- 11. mailto:oferm@hcs.co.il
- 12. mailto:oferm@hcs.co.il
- 13. mailto:gregh@sunsite.unc.edu
- 14. mailto:oferm@hcs.co.il
- 15. mailto:andreas@medman.ag.or.at
- 16. mailto:mark026@ibm.net
- 17. file://localhost/export/sunsite/users/gferg/howto/00_NFS-Root-Client-mini-HOWTO.html#OVERVIEW
-
- Root over nfs clients & server Howto.
- Hans de Goede hans@highrise.nl
-
- v1.0 30 March 1999
-
- Howto setup a server and configure clients for diskless operation from
- a network.
-
- ______________________________________________________________________
-
- Table of Contents
-
-
- 1. Introduction
-
- 1.1 Copyright
- 1.2 Changelog
-
- 2. Basic principle
-
- 2.1 Things can't be that simple
- 2.1.1 Each ws needs its own writable copy of a number of dirs
- 2.1.2 Write access to /home might be needed
- 2.1.3 How does a ws find out it's ip so that it can communicate with the server?
- 2.1.4 What about ws sepecific configuration
- 2.1.5 Miscelancious problems
-
- 3. Preparing the server
-
- 3.1 Building a kernel
- 3.2 Creating and populating /tftpboot, making symlinks for /tmp etc.
- 3.2.1 The automagic part
- 3.2.2 Manual adjustments to some files
- 3.3 Exporting the appropriate file systems and setting up bootp
- 3.3.1 Exporting the appropriate file systems
- 3.3.2 Setting up bootp
-
- 4. Adding workstations
-
- 4.1 Creating a boot disk or bootrom
- 4.1.1 Creating a bootdisk
- 4.1.2 Creating a bootrom
- 4.2 Creating a ws dir
- 4.3 Add entries to /etc/bootptab and /etc/hosts
- 4.4 Booting the ws for the first time
- 4.5 Set the ws specific configuration.
-
- 5. Added bonus: booting from cdrom
-
- 5.1 Basic Principle
- 5.1.1 Things can't be that simple
- 5.2 Creating a test setup.
- 5.3 Creating the cd
- 5.3.1 Creating a boot image
- 5.3.2 Creating the iso image
- 5.3.3 Verifying the iso image
- 5.3.4 Writing the actual cd
- 5.4 Boot the cd and test it
-
- 6. Thanks
-
- 7. Comments
-
-
-
- ______________________________________________________________________
-
- 1. Introduction
-
- This howto is also available at - .
- This document describes a setup for nfs over root. This document
- differs from the other root over nfs howto's in 2 ways:
-
-
- 1. It describes both the server and the client side offering a
- complete solution, it doesn't desribe the generic principles off
- root over nfs although they will become clear. Instead it offers a
- working setup for root over nfs. One of the many possible setup's I
- might add.
-
- 2. This solution is unique in that it shares the root of the server
- with the workstations (ws). Instead of having a mini-root per ws.
- This has a number of advantages:
-
- · low diskspace usage
-
- · any changes on the serverside are also automagicly made at the
- client side, all configuration has only to be done once!
-
- · Very easy adding of new clients
-
- · only one system to maintain
-
- This document is heavily based on a RedHat-5.2 system. Quite a bit of
- prior linux sysadmin experience is assumed in this howto, if you have
- that it shouldn't be a problem to addept this solutions to other
- distributions.
-
- 1.1. Copyright
-
- Well here's the standard howto legal stuff:
-
- This manual may be reproduced and distributed in whole or in part,
- without fee, subject to the following conditions:
-
-
- · The copyright notice above and this permission notice must be
- preserved complete on all complete or partial copies.
-
- · Any translation or derived work must be approved by the author in
- writing before distribution.
-
- · If you distribute this work in part, instructions for obtaining the
- complete version of this manual must be included, and a means for
- obtaining a complete version provided.
-
- · Small portions may be reproduced as illustrations for reviews or
- quotes in other works without this permission notice if proper
- citation is given.
-
-
- Exceptions to these rules may be granted for academic purposes: Write
- to the author and ask. These restrictions are here to protect us as
- authors, not to restrict you as learners and educators.
-
- 1.2. Changelog
-
-
- · v0.1, 20 January 1999: First draft written at the HHS, where the
- setup was originally developed.
-
- · v1.0, 30 March 1999: First released version partially written in
- time of ISM
-
- 2. Basic principle
-
- As already said with this setup the clients share basicly the entire
- root-fs with the server. But the clients ofcourse only get read access
- to it. This is basicly how things work.
-
- 2.1. Things can't be that simple
-
- Unfortunatly things aren't that simple, there are a couple of problems
- the overcome with this simple setup.
-
- 2.1.1. Each ws needs its own writable copy of a number of dirs
-
- A normal linux setup needs to have write access to the following dirs:
-
-
- 1. /dev
-
- 2. /var
-
- 3. /tmp
-
- There are 3 solutions for this, of which one will only work for /dev:
-
-
- 1. mount a ramdisk and populate it by untarring a tarball, or by
- copying a template dir.
-
- · Advantages:
-
- a. It's cleaned up every reboot, which removes tmp files and logs.
- Thus it needs no maintaince unlike server sided dirs.
-
- b. It doesn't take up any space on the server, and that it doesn't
- generate any network traffic. A ramdisk takes less server and
- network resources, and is faster.
-
- · Disadvantages:
-
- a. It takes memory.
-
- b. The logs aren't kept after a reboot, if you really want logging
- of all your clients tell syslog to redirect the logging to your
- server.
-
- 2. create a dir for each ws on the server and mount it rw over nfs.
-
- · Advantages & disadvantages:
-
- a. The above arguments work in reverse for serversided dirs.
-
- 3. With kernel 2.2 devfs can be used for /dev, this is a virtual
- filesystem ala /proc for /dev.
-
- · Advantages:
-
- a. Devfs takes very little memory when compared to a ramdisk / no
- diskspace on the server and is very fast. A normal /dev takes at
- least 1.5 mb since the minimal size for a file (and thus for a
- device) is 1k, and there are somewhere around 1200 devices. You
- can offcourse use a template of a stripped /dev with only the
- entries you need to save some space. 1.5 Mb is a lott for a
- ramdisk and also isn't nice on a server.
- b. Devfs automagicly creates entries for newly added & detected
- devices, so no maintainance is needed.
-
- · Disadvantages:
-
- a. Any changes to /dev like creating symlinks for the mouse and
- cdrom are lost. Devfs comes with a script called rc.devfs to
- save these chances. The script's provided in this howto will
- automagicly restore these symlinks settings by calling rc.devfs
- If you make any changes to /dev you need to call the rc.devfs
- yourself to save them by typing:
-
-
- /etc/rc.d/rc.devfs save /etc/sysconfig
-
-
- As you can see, there are a number of ways to solve this problem. For
- the rest of this Howto the following choices are assumed:
-
-
- · For /dev we'll use Devfs
-
- · For /var and /tmp we'll use a shared ramdisk of 1mb. It's shared to
- use the space as effeciently as possible. /tmp is replaced by a
- symlink to /var/tmp to make the sharing possible.
-
- · Populating the ramdisk with tarballs or template dirs, works
- equally well. But with template dirs it's much easier to make
- changes, thus we'll use template dirs.
-
- 2.1.2. Write access to /home might be needed
-
- Not really a problem in every unix client/server setup /home is
- mounted rw from the server so we'll just do that ;)
-
- 2.1.3. How does a ws find out it's ip so that it can communicate with
- the server?
-
- Luckily for us, this problem has already been solved and the linux
- kernel has support for 2 ways of autoconfiguration of the ip-address:
-
-
- 1. RARP
-
- 2. Bootp
-
- Rarp is the easiest to setup, bootp is the most flexible. Since most
- bootroms only support bootp that's what we'll use.
-
- 2.1.4. What about ws sepecific configuration
-
- On redhat most system dependent config files are already in
- /etc/sysconfig We'll just move those which aren't there and add
- symlinks. Then we mount a seperate /etc/sysconfig on a per ws basis.
- This is really the only distribution dependent part on other
- distributions you can just create a sysconfig dir, move all config
- files which can't be shared there and create symlinks. Also
- /etc/rc.d/rc3.d, or symilar on other dists, might need to be different
- for the server resp the workstations. Assuming that all ws run the
- same services in runlevel 3, we'll just create a seperate 3th runlevel
- for the workstations and the server:
-
-
- 1. Create both a /etc/rc.d/rc3.ws and a /etc/rc.d/rc3.server
-
-
- 2. make /etc/rc.d/rc3.d a symlink to /etc/sysconfig/rc3.d
-
- 3. make /etc/sysconfig/rc3.d a symlink to the apropiate
- /etc/rc.d/rc3.xxx
-
- 4. replace S99local in rc3.ws by a link to /etc/sysconfig/rc.local so
- that each ws can have it's own rc.local
-
- 2.1.5. Miscelancious problems
-
- There are a few problems left:
-
-
- 1. /etc/rc.d/rc.sysinit needs /var, so /var needs to be mounted or
- created before /etc/rc.d/rc.sysinit is run. It would also be nice
- if the ws-specific /etc/sysconfig is mounted before any initscripts
- are run.
-
- · We'll just source a bootup script for the ws in the very top of
- /etc/rc.d/rc.sysinit. Note this script will then ofcourse also be
- sourced by the server itself on boot, so the script has to detect
- this and do nothing on the server.
-
- 2. /etc/mtab needs to be writable:
-
- · This is a tricky one, just create a link to /proc/mounts and create
- an empty file mounts in /proc so that fsck and mount don't complain
- during the initscripts when /proc isn't mounted yet. One note
- smb(u)mount doesn't respect mtab being a link and overwrites it.
- Thus if you want to use smb(u)mount create wrapper scripts that
- restore the symlink.
-
- 3. Preparing the server
-
- Now it's time to prepare the server to serve diskless clients.
-
- 3.1. Building a kernel
-
- The first thing todo is build a kernel with the nescesarry stuff in to
- support root over nfs. Take the following steps to build your kernel:
-
-
- 1. Since we'll be using redhat-5.2 with kernel-2.2 you should asure
- yourself that your redhat-5.2 is kernel-2.2 ready. RedHat has got
- an excellent howto on this.
-
- 2. I use the same kernel for both server and ws, to avoid module
- conflicts since they share the same /lib/modules. If this is not
- possible in your situation, fake different kernel versions by
- editing the version number in the kernel's top makefile. These
- different versionsnumbers will avoid any conflicts.
-
- 3. Besides the usual stuff the kernel should have the following:
-
- · ext2 compiled in (if used on server, or for both)
-
- · nfs and root-over-nfs compiled in (if used on client or both), to
- get the nfs over root option in 2.2 enable ip-autoconfig in the
- network options. We'll use bootp as configuration method.
-
- · ws networkcard support compiled in (if used on client or both)
-
- · compile devfs in (required for client, also nice for server)
-
- · anything else you normally use, modules for all other devices used
- on either the server or all / some ws etc.
- 4. The kernel-src needs to be edited to make the default root-over-nfs
- mount: /tftpboot//root instead of just /tftpboot/. This is
- to get a clean tree in /tftpboot with one dir per ws containing
- both the root for it (a link to the actual server root) and any ws
- specific dirs.
-
- · For 2.0 This is a define in: "include/linux/nfs_fs.h" called
- "NFS_ROOT"
-
- · For 2.2 This is a define in: "fs/nfs/nfsroot.c"
-
- 5. Now just compile the kernel as usual, see the kernel-howto.
-
- 6. If you don't have /dev/nfsroot yet, create it by typing:
-
- mknod /dev/nfsroot b 0 255.
-
-
- 7. After compiling the kernel set the root to nfsroot by typing:
-
- rdev /zImage /dev/nfsroot
-
-
- 8. Before booting with devfs you need to make a few changes to
- /etc/conf.modules, append the contents of the conf.modules in the
- devfs documentation to it.
-
- 9. Since this new kernel is compiled for autoconfig of ip's it will
- try to autoconf the ip of the server during bootup. Which ofcourse
- will fail since it gives out the ip's. To avoid a long timeout add:
- append="ip=off" To the linux section of /etc/lilo.conf.
-
- 10.
- Run lilo and boot the new kernel.
-
- 11.
- Due to devfs you'll have lost all symlinks on the server. With
- redhat this is usually /dev/mouse and /dev/cdrom. Recreate these.
- If you also used to use special ownerships, chown to appropiate
- files in /dev. Now save the /dev settings (in /etc/sysconfig, since
- they might be ws specific):
-
- · Copy rc.devfs from the devfs documentation in the kernel source to
- /etc/rc.d/rc.devfs and make it executable
-
- · Save the settings by typing:
-
- /etc/rc.d/rc.devfs save /etc/sysconfig
-
-
- 3.2. Creating and populating /tftpboot, making symlinks for /tmp etc.
-
- The next step is to create and populate /tftpboot
-
- 3.2.1. The automagic part
-
- This is all handled by a big script since putting a long list of
- commands into this howto seemed pretty useless to me. If you want todo
- this manual just read the script and type it in as you go ;)
-
- This setup script thus some nasty things like nuke /tmp, temporary
- kill syslog, umount /proc. So make sure that noone is using the
- machine during this, and that X isn't running. Just making sure your
- the only one logged in on a text-console is enough, no need to change
- runlevels.
-
- DISCLAIMER: this script has been tested but nevertheless if it messes
- up your server your on your own. I can take no responsibility what so
- ever. Lett me repeat this howto is only for experienced linux
- sysadmins. Also this is script is designed to be run once and I really
- mean once. Running it twice will nuke: /etc/fstab,
- /etc/X11/XF86Config, /etc/X11/X and /etc/conf.modules.
-
- Now with that said, just cut and paste the script make it executable,
- execute it and pray to the holy penguin that it works ;)
-
-
-
- ______________________________________________________________________
- #!/bin/sh
-
- SERVER_NAME=`hostname -s`
-
- ###
- echo creating /etc/rc.d/rc.ws
- #this basicly just echos the entire script ;)
- echo "#root on nfs stuff
-
- SERVER=$SERVER_NAME
-
- #we need proc for mtab, route etc
- mount -t proc /proc /proc
-
- IP=\`ifconfig eth0|grep inet|cut --field 2 -d ':'|cut --field 1 -d ' '\`
-
- #if the first mount fails we're probably the server, or atleast something is
- #pretty wrong, so only do the other stuff if the first mount succeeds
- mount \$SERVER:/tftpboot/\$IP/sysconfig /etc/sysconfig -o nolock &&
- {
- #other mounts
- mount \$SERVER:/home /home -o nolock
- mount \$SERVER:/ /\$SERVER -o ro,nolock
-
- #/var
- echo Creating /var ...
- mke2fs -q -i 1024 /dev/ram1 1024
- mount /dev/ram1 /var -o defaults,rw
- cp -a /tftpboot/var /
-
- #network stuff
- . /etc/sysconfig/network
- HOSTNAME=\`cat /etc/hosts|grep \$IP|cut --field 2\`
- route add default gw \$GATEWAY
- ifup lo
- }
-
- #restore devfs settings
- /etc/rc.d/rc.devfs restore /etc/sysconfig
-
- umount /proc" > /etc/rc.d/rc.ws
-
- ###
- echo splitting runlevel 3 for the client and server
- mv /etc/rc.d/rc3.d /etc/rc.d/rc3.server
- cp -a /etc/rc.d/rc3.server /etc/rc.d/rc3.ws
- rm /etc/rc.d/rc3.ws/*network
- rm /etc/rc.d/rc3.ws/*nfs
- rm /etc/rc.d/rc3.ws/*nfsfs
- rm /etc/rc.d/rc3.ws/S99local
- ln -s /etc/sysconfig/rc.local /etc/rc.d/rc3.ws/S99local
- ln -s /etc/rc.d/rc3.server /etc/sysconfig/rc3.d
- ln -s /etc/sysconfig/rc3.d /etc/rc.d/rc3.d
-
- ###
- echo making tmp a link to /var/tmp
- rm -fR /tmp
- ln -s var/tmp /tmp
-
- ###
- echo moving various files around and create symlinks for them
- echo mtab
- /etc/rc.d/init.d/syslog stop
- umount /proc
- touch /proc/mounts
- mount /proc
- /etc/rc.d/init.d/syslog start
- rm /etc/mtab
- ln -s /proc/mounts /etc/mtab
- echo fstab
- mv /etc/fstab /etc/sysconfig
- ln -s sysconfig/fstab /etc/fstab
- echo X-config files
- mkdir /etc/sysconfig/X11
- mv /etc/X11/X /etc/sysconfig/X11
- ln -s ../sysconfig/X11/X /etc/X11/X
- mv /etc/X11/XF86Config /etc/sysconfig/X11
- ln -s ../sysconfig/X11/XF86Config /etc/X11/XF86Config
- echo conf.modules
- mv /etc/conf.modules /etc/sysconfig
- ln -s sysconfig/conf.modules /etc/conf.modules
- echo isapnp.conf
- mv /etc/isapnp.conf /etc/sysconfig
- ln -s sysconfig/isapnp.conf /etc/isapnp.conf
-
- ###
- echo creating a template dir for the ws directories
- echo /tftpboot/template
- mkdir /home/tftpboot
- ln -s home/tftpboot /tftpboot
- mkdir /tftpboot/template
- mkdir /$SERVER_NAME
- echo root
- ln -s / /tftpboot/template/root
- echo sysconfig
- cp -a /etc/sysconfig /tftpboot/template/sysconfig
- rm -fR /tftpboot/template/sysconfig/network-scripts
- ln -s /$SERVER_NAME/etc/sysconfig/network-scripts \
- /tftpboot/template/sysconfig/network-scripts
- echo NETWORKING=yes > /tftpboot/template/sysconfig/network
- echo `grep "GATEWAY=" /etc/sysconfig/network` >> /tftpboot/template/sysconfig/network
- echo "/dev/nfsroot / nfs defaults 1 1" > /tftpboot/template/sysconfig/fstab
- echo "none /proc proc defaults 0 0" >> /tftpboot/template/sysconfig/fstab
- echo "#!/bin/sh" > /tftpboot/template/sysconfig/rc.local
- chmod 755 /tftpboot/template/sysconfig/rc.local
- rm /tftpboot/template/sysconfig/rc3.d
- ln -s /etc/rc.d/rc3.ws /tftpboot/template/sysconfig/rc3.d
- rm /tftpboot/template/sysconfig/isapnp.conf
- echo var
- cp -a /var /tftpboot/var
- rm -fR /tftpboot/var/lib
- ln -s /$SERVER_NAME/var/lib /tftpboot/var/lib
- rm -fR /tftpboot/var/catman
- ln -s /$SERVER_NAME/var/catman /tftpboot/var/catman
- rm -fR /tftpboot/var/log/httpd
- rm -f /tftpboot/var/log/samba/*
- for i in `find /tftpboot/var/log -type f`; do cat /dev/null > $i; done
- rm `find /tftpboot/var/lock -type f`
- rm `find /tftpboot/var/run -type f`
- echo /sbin/fsck.nfs
- echo "#!/bin/sh
- exit 0" > /sbin/fsck.nfs
- chmod 755 /sbin/fsck.nfs
-
- echo all done
-
- ______________________________________________________________________
-
-
-
- 3.2.2. Manual adjustments to some files
-
- Now we need to make a few manual adjustments to the server:
-
-
- 1. The ws setup script has to be sourced at the very beginning of
- rc.sysinit, so add the following lines directly after setting the
- PATH:
-
- ___________________________________________________________________
- #for root over nfs workstations.
- /etc/rc.d/rc.ws
-
- ___________________________________________________________________
-
-
-
- 2. Strip /etc/rc.d/rc3.ws to a bare minimum. It might be useful to
- create something like rc.local.ws but I'll leave that up to you.
- Network and nfsfs are already setup.The following have been already
- removed / updated by the automagic script:
-
- · network
-
- · nfsfs
-
- · nfs
-
- · rc.local
-
- 3.3. Exporting the appropriate file systems and setting up bootp
-
- The server must ofcourse export the appropriate filesystems and asign
- the ip addresses to the clients.
-
- 3.3.1. Exporting the appropriate file systems
-
- We need to export some dir's for the workstations so for the situation
- here at the university I would add the following to /etc/exports:
-
-
- ______________________________________________________________________
- / *.st.hhs.nl(ro,no_root_squash)
- /home *.st.hhs.nl(rw,no_root_squash)
-
- ______________________________________________________________________
-
-
-
- Ofcourse use the apropriate domain ;) and restart nfs by typing:
-
-
- /etc/rc.d/init.d/nfs restart
-
-
- Note for knfsd users: knfsd doesn't allow you to have multiple exports
- on one partition with different permissions. Also knfsd doesn't allow
- clients to go past partition boundaries for example if a client mounts
- / and /usr is a different partition it won't have access to /usr. Thus
- if you use knfsd, at least /home should be on a different partition,
- the server prepare script already puts /tftpboot in /home so that
- doesn't need a seperate partition. If you've got any other partitions
- your clients should have access to export them seperatly and add mount
- commands for them to /etc/rc.d/rc.ws.
-
-
- 3.3.2. Setting up bootp
-
-
- 1. If bootp isn't installed yet install it. It comes with RedHat.
-
- 2. Edit /etc/inetd.conf and uncomment the line beginning with bootps,
- if you want to use a bootprom uncomment tftp while your at it.
-
- 3. Restart inetd by typing:
-
- /etc/rc.d/init.d/inetd restart
-
-
- 4. Adding workstations
-
- Now that the server is all done, we can start adding workstations.
-
- 4.1. Creating a boot disk or bootrom
-
- You'll need ot create a bootrom and / or a bootdisk to boot your
- workstation.
-
- 4.1.1. Creating a bootdisk
-
- Even if you wish to use a bootrom its wise to first test with a
- bootdisk, to create a boot disk just type:
-
-
- dd if=//zImage of=/dev/fd0
-
-
- 4.1.2. Creating a bootrom
-
- There are a few free package's out there to create bootroms:
-
-
- 1. netboot, this is IMHO the most complete free package out there. It
- uses standard dos packet drivers so allmost all cards are
- supported. One very usefull hint I got on there mailing list was to
- pklite the packetdrivers since some commercial drivers are to big
- to fit into the bootrom. Netboot's documentation is complete
- enough, so I won't waste any time reproducing it here, it should be
- more then sufficient to create a bootrom and boot a ws with it.
- Netboot's webpage is: http://www.han.de/~gero/netboot/
-
- 2. etherboot, this is the other free package out there it has got a
- few nice features like dhcp support, but has limited driver support
- as it uses its own driver format. I haven't used this so I really
- can't give anymore usefull info. Etherboot's webpage is:
- http://www.slug.org.au/etherboot/
-
- About the roms themselves. Most cards take ordinary eproms with an 28
- pins dip housing. These eproms come in size upto 64kB. For most cards
- you'll need 32kB eproms with netboot. Some cards drivers will fit into
- 16kB but the price difference of the eproms is minimal. These eproms
- can be burned with any ordinairy eprom burner.
-
- 4.2. Creating a ws dir
-
- Just copy over the template by typing:
-
-
- cd /tftpbootcp -a template
-
-
-
- You could of course also copy over the dir of a workstation with
- identical mouse, graphicscard and monitor and ommit the configuration
- in step 5.4.
-
- 4.3. Add entries to /etc/bootptab and /etc/hosts
-
- Edit /etc/bootptab and add an entry for your test ws, an example entry
- is:
-
-
- ______________________________________________________________________
- nfsroot1:hd=/tftpboot:vm=auto:ip=10.0.0.237:\
- :ht=ethernet:ha=00201889EE78:\
- :bf=bootImage:rp=/tftpboot/10.0.0.237/root
-
- ______________________________________________________________________
-
-
-
- Replace nfsroot1 by the hostname you want your ws to have. Replace
- 10.0.0.237 by the ip you want your ws to have (do this twice) and
- replace 00201889EE78 by the MAC-ADDRESS of your ws. If you don't know
- the MAC-ADDRESS of the ws, just boot it with the just created boot
- disk and look for the MAC-ADDRESS in the boot messages. There's a
- chance bootpd is already running so just to make sure try to restart
- it by typing:
-
-
- killall -HUP bootpd
-
-
- Don't worry if it fails, that just means it wasn't running, inetd will
- start it when asked too.
-
- 4.4. Booting the ws for the first time
-
- Just boot the ws from the bootdisk. This should get you a working ws
- in textmode, with the exact same setup as your server except for the
- ip-nr and the running services. Even if you want to use a bootprom
- it's wise to first test with the bootdisk, if that works you can try
- to boot with the bootrom see the bootroms documentation for more info.
-
- 4.5. Set the ws specific configuration.
-
- Now it's time to configure any ws specific settings:
-
-
- 1. First off all to get the mouse working, just run mouseconfig. To
- apply the changes, and check that the mouse works type:
-
- /etc/rc.d/init.d restart
-
-
- 2. Run Xconfigurator, when Xconfigurator has probed the card and you
- can press ok don't! Since we have moved the symlink for the Xserver
- from /etc/X11/X to /etc/sysconfig/X11/X Xconfigurator will fail to
- create the proper link. Thus to make sure the rest of Xconfigurator
- goes well, switch to another console and create the link in
- /etc/sysconfig/X11 to the advised server. Now just finish
- Xconfigurator and test X.
-
- 3. Configure anything else which is different then the server /
- template:
-
- · sound: You probaly need to modify isapnp.conf and conf.modules,
- both are already made links to /etc/sysconfig by the server setup
- script.
-
- · cdrom: Link in /dev, entry in /etc/fstab? etc.
-
- · rc.local: Make any nescesarry changes.
-
- 4. Save the links and any other changes to /dev type:
-
- /etc/rc.d/rc.devfs save /etc/sysconfig
-
-
- 5. All done.
-
- 5. Added bonus: booting from cdrom
-
- Much of the above also goes for booting from cdrom. Since I wanted to
- document howto boot from cdrom anyway, I document it in here to avoid
- typing a lott of the same twice.
-
- Why would one want to boot a machine from cd-rom? Booting from cdrom
- is interesting everywhere where one wants to run a very specific
- application, like a kiosk, a library database program or an intenet
- cafe, and one doesn't have a network or a server to use a root over
- nfs setup.
-
- 5.1. Basic Principle
-
- The basic principle is wants again simple, boot with a cdrom as root.
- To make this possible we'll use the rockridge extension to put a unix
- like filesystem on a cd and the Eltorito extension to make cd's
- bootable.
-
- 5.1.1. Things can't be that simple
-
- Ofcourse this setup also has a few problems. most are the same as
- above:
-
-
- 1. We'll need write access to: /dev, /var & /tmp.
-
- · We'll just use the same solutions as with root over nfs (see
- above):
-
- · For /dev we'll use Devfs
-
- · For /var and /tmp we'll use a shared ramdisk of 1mb. It's shared to
- use the space as effeciently as possible. /tmp is replaced by a
- symlink to /var/tmp to make the sharing possible.
-
- · Populating the ramdisk with tarballs or template dirs, works
- equally well. But with template dirs it's much easier to make
- changes, thus we'll use template dirs.
-
- 2. Some apps need write access to /home.
-
- · Put the homedir of the user's who will be running the application
- in /var, and populate it wiht the rest of /var every boot.
-
- 3. /etc/mtab needs to be writable:
-
- · Create a link to /proc/mounts and create an empty file mounts in
- /proc, see above.
-
-
-
- 5.2. Creating a test setup.
-
- Now that we know what we want todo and how, it's time to create a test
- setup:
-
-
- 1. For starters just take one of the machines which you want to use
- and put in a big disk and a cd-burner.
-
- 2. Install your linux of choice on this machine, and leave a 650mb
- partition free for the test setup. This install will be used to
- make the iso-image and to burn the cd's from, so install the
- nescesarry tools. It will also be used to restore any booboo's
- which leave the test setup unbootable.
-
- 3. On the 650 mb partition install your linux of choice with the setup
- you want to have on the cd, this will be the test setup
-
- 4. Boot the test setup.
-
- 5. Compile a kernel as described in Section 3.1, follow all the steps,
- the changes need for devfs are still needed! At step 3 of Section
- 3.1 put in the following:
-
- · isofs compiled in
-
- · devfs compiled in
-
- · cdrom support compiled in
-
- · everything else you need either compiled in or as module.
-
- 6. Configure the test setup:
-
- · Create the user which we'll be running the application.
-
- · Put it's homedir in /var.
-
- · Install the application if needed.
-
- · Configure the application if needed.
-
- · Configure the user so that the application is automagicly run after
- login.
-
- · Configure linux so that it automaigcly logs in the user.
-
- · Configure anything else which needs configuring.
-
- 7. Test that the test setup automagicly boots into the apllication and
- everything works.
-
- 8. Boot the main install and mount the 650 mb partition on /test of
- the main install.
-
- 9. Put the following in a file called /test/etc/rc.d/rc.iso, this file
- we'll be sourced at the begining of rc.sysinit to create /var
-
-
-
- ___________________________________________________________________
- #/var
- echo Creating /var ...
- mke2fs -q -i 1024 /dev/ram1 1024
- mount /dev/ram1 /var -o defaults,rw
- cp -a /lib/var /
-
- #restore devfs settings, needs proc
- mount -t proc /proc /proc
- /etc/rc.d/rc.devfs restore /etc/sysconfig
- umount /proc
-
- ___________________________________________________________________
-
-
-
- 10.
- Edit /test/etc/rc.sysinit comment the lines we're the root is
- remounted rw and add the following 2 lines directly afer setting
- the PATH:
-
- ___________________________________________________________________
- #to boot from cdrom
- . /etc/rc.d/rc.iso
-
- ___________________________________________________________________
-
-
-
- 11.
- Copying the following to a script and executing it, this wil create
- a template for /var and make /tmp and /etc/mtab links.
-
- ___________________________________________________________________
- #!/bin/sh
- echo tmp
- rm -fR /test/tmp
- ln -s var/tmp /test/tmp
-
- ###
- echo mtab
- touch /test/proc/mounts
- rm /test/etc/mtab
- ln -s /proc/mounts /test/etc/mtab
-
- ###
- echo var
- mv /test/var/lib /test/lib/var-lib
- mv /test/var /test/lib
- mkdir /test/var
- ln -s /lib/var-lib /test/lib/var/lib
- rm -fR /test/lib/var/catman
- rm -fR /test/lib/var/log/httpd
- rm -f /test/lib/var/log/samba/*
- for i in `find /test/lib/var/log -type f`; do cat /dev/null > $i; done
- rm `find /test/lib/var/lock -type f`
- rm `find /test/lib/var/run -type f`
-
-
- ___________________________________________________________________
-
-
-
- 12.
- Remove the creation of /etc/issue* from /test/etc/rc.local it will
- only fail.
- 13.
- Now boot the test partition again, it will be read only just like a
- cdrom. If something doesn't work reboot to the working partition
- fix it, try again etc. Or you could remount / rw ,fix it then
- reboot straight into to test partition again. To remount / rw type:
-
- mount -o remount,rw /
-
-
- 5.3. Creating the cd
-
- 5.3.1. Creating a boot image
-
- First of all boot into the workign partition. To create a bootable cd
- we'll need an image of a bootable floppy. Just dd-ing a zimage doesn't
- work since the loader at the beginning of the zimage doesn't seem to
- like the fake floppydrive a bootable cd creates. So we'll use syslinux
- instead.
-
-
- 1. Get boot.img from a redhat cd
-
- 2. Mount boot.img somewhere through loopback by typing:
-
- mount boot.img somewhere -o loop -t vfat
-
-
- 3. Remove everything from boot.img except for:
-
- · ldlinux.sys
-
- · syslinux.cfg
-
- 4. Cp the kernel-image from the test partition to boot.img.
-
- 5. Edit syslinux.cfg so that it contains the following, ofcourse
- replace zImage by the appropiote image name:
-
- ___________________________________________________________________
- default linux
-
- label linux
- kernel zImage
- append root=/dev/
-
- ___________________________________________________________________
-
-
-
- 6. Umount boot.img:
-
- umount somewhere
-
-
- 7. If your /etc/mtab is a link to /proc/mounts umount won't
- automagicly free /dev/loop0 so free it by typing:
-
- losetup -d /dev/loop0
-
-
- 5.3.2. Creating the iso image
-
- Now that we have the boot image and an install that can boot from a
- readonly mount it's time to create an iso image of the cd:
-
-
- 1. Copy boot.img to /test
-
- 2. Cd to the directory where you want to store the image make sure
- it's on a partition with enough free space.
-
- 3. Now generate the image by typing:
-
- mkisofs -R -b boot.img -c boot.catalog -o boot.iso /test
-
-
- 5.3.3. Verifying the iso image
-
-
- 1. Mounting the image throug the loopbackdevice by typing:
-
- mount boot.iso somewhere -o loop -t iso9660
-
-
- 2. Now verify that the contents is ok.
-
- 3. Umount boot.iso:
-
- umount somewhere
-
-
- 4. If your /etc/mtab is a link to /proc/mounts umount won't
- automagicly free /dev/loop0 so free it by typing:
-
- losetup -d /dev/loop0
-
-
- 5.3.4. Writing the actual cd
-
- Assuming that you've got cdrecord installed and configured for your
- cd-writer type:
-
-
- cdrecord -v speed= dev= boot.iso
-
-
- 5.4. Boot the cd and test it
-
- Well the title of this paragraph says it all ;)
-
- 6. Thanks
-
-
- · The HHS (Haagse Hoge School) a dutch college where I first
- developed and tested this setup for use in a couple of labs. And
- where the initial version of this HOWTO was written.
-
- · ISM a dutch company where I'm doing my final project. Part of the
- project involves diskless machines, so I got to develop this setup
- further and had the time to update this HOWTO.
-
- · All the users who will give me usefull input once this first
- version is out ;)
-
- 7. Comments
-
- Comments suggestions and such are welcome. They can be send to Hans de
- Goede at: j.w.r.degoede@et.tudelft.nl
-
- Root over NFS - Another Approach
- George Gousios, cs98011@icsd.aegean.gr
- v1.0, 2001-09-12
-
- This HOWTO does not intend to replace the existing Root over NFS
- Howto's. It is just another approach, particularly useful in large
- system installations. It is the result of many days of trying to
- setup a system for the University of the Aegean computer labs. The
- installation method described here is up and running. The HOWTO is
- dedicated to all of those guys who programmed these exceptionally good
- OS and tools. Also dedicated to all people that encouraged me to
- write it.
- ______________________________________________________________________
-
- Table of Contents
-
-
- 1. Introduction
-
- 1.1 The setting
- 1.2 The alternatives
- 1.3 General Principles
-
- 2. Setting up the server
-
- 2.1 Setting up the NFS server
- 2.2 Setting up the DHCP/BOOTP server
- 2.3 Preparing the base system
-
- 3. Setting up the clients
-
- 3.1 Errata
- 3.2 Fiddling with scripts and files!
- 3.2.1 How to setup a swap partition
- 3.2.2 Modifying
- 3.2.3 Copying password files
- 3.3 Booting the base system
- 3.4 Configuring the system
- 3.4.1 Configuring the language
- 3.4.2 The X window system
- 3.4.3 Configuring network access for KDE2
-
- 4. Preparing the boot disk
-
- 4.1 Building a kernel
- 4.2 Creating the boot disk
- 4.3 The kernel command line
-
- 5. The magic time
-
- 6. Other Stuff
-
- 6.1 Contributors
- 6.2 Copyrights
- 6.3 Contacting the author
- 6.4 Changelog
-
- 7. Appendix
-
- 7.1 Appendix A - A script for creating host directories
- 7.2 Appendix B - A script to create the dhcpd.conf file using
- 7.2.1 The arp.dat2dhcpd.conf script
- 7.3 Appendix C - A sample XF86Config file
-
-
-
- ______________________________________________________________________
-
- 1. Introduction
-
- This document does not resemble a common HOWTO, meaning referencing to
- general principles, but it is rather an on-hand approach to a by
- nature complex matter. It borrows the structure of the current Root
- over NFS , but differs from it in the following points:
-
-
- · It provides a working solution fom the distribution used. The
- distribution specific points should be applicable to all major
- distributions (RedHat,SuSE,Debian).
-
- · It uses more up to date tools, ex NFS v3.0, kernel 2.4.0, dhcp
- instead of bootparamd.
-
- · All steps are described in detail, letting the reader to adapt them
- to his own system. No scripts!
-
- This HOWTO expects that you have a general knowledge of what you are
- up to, so first read the Diskless Nodes HOW-TO.
-
- 1.1. The setting
-
- It is a common case a University computer lab to have a lot PC's
- running Windows 98 or/and NT and a powerful UNIX server to satisfy the
- need of an alternative operating environment. This UNIX server is
- most of times idle or meerly accessed by telnet and running stupid
- tasks. On the other hand, students, especially those attending a
- computer science department, feel like taking full advantage of it,
- just for fun or for "educational purposes" (breaking in, hacking
- it...). The restrictive environment of telnet does not allow us to
- enjoy the use of a power server.There are 2 alternatives to that:
-
- · Try to persuade the department' s headmaster to approve of the
- purchase of a bunch of new Unix workstations.
-
- · Try to persuade the same guy to approve of transforming the server
- to a diskless node server.
-
- The network at the computer lab consists of the following.
-
-
- · UNIX server: SUN Enterprise 3500 with 2 64 bit SPARC@366 Mhz
- processors and 512 MB of memory. A real monster, isn't it?
-
- · "Dumb" target workstations: 60-70 PC's with variable
- configurations, ranging from PII 266 to PIII 450 with 64-128 MB
- RAM.
-
- The task I had to accomplish was the following: Provide a complete
- working solution without new expenses and without modifying anything
- but the necessary on the server.
-
-
- 1.2. The alternatives
-
- Being the responsible for the project, I had to choose between a
- variety of solutions about it. I choose the following, for the
- reasons illustrated:
-
- · The new 2.4 kernel: It provides a robust and fast solution, using
- less memory than the old 2.2 series. If it is important for your
- users to attach devices to their PC's then it is the only solution.
- Also provides NFS v3, and more efficient memory management.
- · The KDE 2.1.1 desktop environment: VERY stable, easy to use,
- Internet enabled, makes the transition from Windows to Linux
- desktop almost effortless. GNOME + Afterstep is another option, but
- not as mature as a solution as KDE.
-
- · SuSE 7.0 distribution: My favorite one, IMHO the most balanced
- between ease of use and understanding of a Linux system structure.
-
-
- 1.3. General Principles
-
- To be able to boot a Linux system, you have to provide it with the
- following:
-
- · The /sbin directory. There exists the init programm, which is
- responsible for starting other programms and start up scripts
- during the boot process. Also, the /sbin directory contains the
- startup scripts in the case of SuSE, some useful programms like the
- portmap programm and many other programms that are needed before
- you mount the /usr directory.
-
- · The /lib directory. It contains the libc libraries that are
- absolutely necessary if your init is dynamically linked.
-
- · The /bin directory. It contains file commands and shells for
- running startup scripts.
-
- · The /etc directory. It contains configuration files for most
- programms and the rc.d directories that is the default for startup
- scripts.
-
- · The /var directory. It is a spool area for programms that want to
- write somewhere. It is divided into many subdirectories with
- alternate usability.
-
- · The /dev directory. It contains character and block special devices
- that allow programms to communicate with the computers devices via
- the kernel.
-
- You should notice that after a clean install, the total size of
- these directories is not that big, ranging from 30 to 40 MB. The
- main load of files exists in the /usr and /opt directories. So, it
- is possible to create a directory for every diskless client
- containing the above listed directories and mount points for
- directories like /usr that will be exported by the server. The
- boot process, as assumed by this document, is the following:
-
- 1. The user reboots the computer, and using a diskette boots the Linux
- kernel.
-
- 2. The kernel takes control of the system, identifies the system
- devices, and uses BOOTP to obtain the IP address matching the NIC
- 's hardware address.
-
- 3. The init programm is started. Before switching to a run level, it
- calls a script described in the /etc/inittab file. This script is
- responsible for building the library cache, initialise and mount a
- swap file, load some system specific kernel modules and set the
- hostname.
-
- 4. The boot script finishes and the init programm switches to the
- specified runlevel. It starts to execute the scripts located into
- the /etc/rc.d/rcX directory where 'X' is the name of the runlevel.
- These scripts are responsible for starting the portmapper and
- mounting the NFS exported /usr, /home and /opt directories.
-
- 5. The user is able to login.
-
- To sum up, the system administrator has to do the following tasks:
-
- · Prepare a clean install of the system to be exported to the
- diskless hosts.
-
- · Create the host specific directories
-
- · Control what is going to be started during the diskless clients'
- boot proces
-
- · Prepare the server to export some directories and start a bootp
- service.
-
-
- 2. Setting up the server
-
- The first, and less tricky, thing to do is to setup the server. The
- server must be prepared to run these services:
-
- · NFS, preferably version 3, for exporting the following directories:
- /usr, /lib/modules, /opt (at least at SuSE) and /home (unless you
- have a dedicated file server).
-
- · DHCP server (in bootp mode), for matching the clients' MAC
- addresses to IP addresses.
-
- Also, the administrator has to create directories for each client,
- containing nessesary startup files and programs. The directory
- scheme created for the installation described was like this one:
-
-
-
- ______________________________________________________________________
- /usr/local/linux-
- |-/base-
- | |-/bin
- | |-/sbin
- | |-/etc
- |
- |-/workstations-
- | |
- | |-195.251.160.100
- | | |-/bin
- | | |-/sbin
- | | |-/etc
- | |
- | |-195.251.160.101
- | |-195.251.160.102
- | |-base(symbolic link to ../base)
- ______________________________________________________________________
-
-
-
- The /base directory contains the whole file system you want to export
- to your clients. The per IP directories contain files that are needed
- before mounting the /usr or /lib/modules directories, like the /etc
- folder. This is a confortable directory structure for 2 purposes: i)
- You can easily create a basic system at the base directory and copy
- the per workstation files at the workstation directories easily, with
- an entry level bash script ii) You can easily add or delete or update
- workstations by modifying the directories under /workstations. A
- script for copying the appropriate files (which will be discused
- later) can be found in Appendix A.
- 2.1. Setting up the NFS server
-
- An NFS server can be set up in two ways:
-
- · Using the /etc/exports file at BSD-compliant Unices like Linux of
- FreeBSD.
-
- · Using the /etc/dfs/dfstab at SysV Unices like Solaris.
-
- /etc/exports: The /etc/exports file controls the directories to be
- exported and the export options per workstation. It has a
- structure like the following (Linux):
-
-
- ______________________________________________________________________
- /path/to/dir1 ws1(options) ws2(options)....
- /path/to/dir2 ws3(options) ws1(options)....
- ______________________________________________________________________
-
-
-
- Options include ro or rw, root_squash, wsize, tcp, version.
-
- Have a look at the nfs or the exports man page and the NFS Howto for a
- more detailed description of what these options mean.
-
- /etc/dfs/dfstab:A typical dfstab file on Solaris should look like the
- following:
-
-
- ______________________________________________________________________
- share -F nfs -o rw=193.250.160@,ro=193.250.161@ /export/home
- share -F nfs -o ro=193.250.160@,root=193.250.161.132 /export/engineering
- ______________________________________________________________________
-
-
-
- Of course, these options are discused in detail at the dfstab man
- page.
-
- The directories we want to export are /usr/local/linux/base/usr,
- /usr/local/linux/base/opt, /usr/local/linux/base/lib/modules and
- /home, assuming that you 've followed the suggested structure.
-
- Optimising NFS
-
- Of course, this is none of our business but here are some general
- principles:
-
- · Reduce the TCP window size (parameter wsize for Linux) to whatever
- is closest to the MTU of your network type. For Ethernet, a good
- value of wsize is 2048 bytes as long as the MTU is 1536 bytes.
- This is generally a good idea because the main traffic load between
- the clients and the server consists of little packets and only in
- the case of starting large programms like X or StarOffice there is
- a big number of fragmented packets. Of course this may vary in your
- case, according to the needs of your users.
-
- · If you plan to have a large installation, break the space for your
- workstations into 2 or more SCSI disks. This will allow consequent
- writes and reads on both disks, increasing responce and reducing
- latency before a request completes
-
- · Always use NFS v3 over TCP. The main reason for migrating from v2
- to v3 is the writeback case it offers on both the workstation and
- the server. Also, mounting NFS over TCP lets you use the first
- recomentation. \end{itemize} For further optimising use a packet
- analyzer like Ethereal or tcpdump and dicide your needs.By the way,
- Sun has written an excellent guide to optimizing NFS performance
- which, although emphasised on Solaris, is applicable to every
- modern Unix and is accessible online at http://docs.sun.com
- .
-
- 2.2. Setting up the DHCP/BOOTP server
-
- Although there are many DHCP or BOOTP servers 'out there', some of
- which are proprietary, the best option is to use the reference IETF
- DHCP server. It is the least vulnerable and the most extensible DHCP
- available. The main server configuration is done through the
- /etc/dhcpd.conf file. This file is divided into two sections, the
- general server configuration and the host specific configuration. A
- typical dhcpd.conf file looks like this, in case that the DHCP/BOOTP
- server is used in BOOTP mode:
-
-
- subnet 193.250.160.0 netmask 255.255.255.0 {
- range 193.250.160.10 193.250.160.12;
- }
-
- host george{
- hardware ethernet 00:60:08:2C:22:20;
- fixed-address 193.250.160.10;
- }
-
- host earth{
- hardware ethernet 00:A0:24:A5:FD:E0;
- fixed-address 193.250.160.12;
- }
-
-
-
- This structure is fairly easy to be understood by everyone. For every
- diskless client we have to supply the programm with a 'host'
- declaration providing a pair of hardware and IP adresses. The host
- name provided in the 'host' statement can be everything, but there is
- a conversion to use the real host name of the client having the
- specific IP. The range statement in the subnet declaration is not
- necessary to be the range that you want your clients to have. In fact,
- if these clients are normal workstations with an operating system that
- during its boot uses DHCP to obtain an IP address it is not
- recommended to have the same IP for their operation as diskless
- clients. If you have specific needs, have a look at dhcpd.conf man
- page.
-
- Another difficulty is how to obtain the IP - MAC address pairs for a
- large network. The solution is a nice little programm called arpwatch.
- This programm runs at the background and keeps track of the IP - MAC
- address pairs of the computers that your computer has contacted in a
- file that you have specified. The only thing you have to do is to ping
- the computers you want. At Appendix B there is a script that starts
- arpwatch, pings a range of subsequent IP's and creates the dhcpd.conf
- file. If you want to do it manually, start arpwatch when your network
- is at its peak of usage and wait for some time. On a shared medium
- network (Ethernet, Tokenring) arpwatch will track down all different
- IP 's and hardware addresses.
-
-
- 2.3. Preparing the base system
-
- To prepare the base system just install your favorite distribution to
- a mountable partition on a hard disk with a Unix like operating system
- already installed. Install all the programms you want to be available
- to your users. Then you have to transfer the whole partition
- preserving the links and the character or block devices. This is best
- done using the tar programm. Boot the previously installed system and
- execute the following command, assuming that you have mounted the new
- partition at /mnt:
-
-
- tar cpvf system.tar /mnt/.
-
-
-
- This command will create a tar archive at the current directory with
- the whole system to be served to the diskless clients. Then just copy
- the tar archive to the server using a CDROM or through the network and
- extract it at the base directory. The command to do this is:
-
-
- tar xvf system.tar /usr/local/linux/base
-
-
-
- 3. Setting up the clients
-
-
- 3.1. Errata
-
- In order to setup the clients, we have to work on the base system.
- First, we will make some modifications to the startup scripts by hand
- and second we will boot a workstation with the base system to make
- sure it works and to polish some details. Note that this part is very
- distribution specific and perhaps some of those described here are not
- applicable to your case. I can only guarantee that this works for
- SuSE 7.0. Please, feel free to send me distribution specific copies of
- this page!
-
- 3.2. Fiddling with scripts and files!
-
- After init is started, it executes a script described in /etc/inittab.
- This script has a very spesific job to do: Bring the system in a state
- that other programms can be started. In most distributions I can think
- of this script does the following:
-
- 1. Mounts the /proc, /dev/pts and swap filesystems.
-
- 2. Activates raid arrays and fscks the root filesystem.
-
- 3. Adjusts the clock.
-
- 4. Starts the kernel deamon for autoloading of modules.
-
- 5. Executes user defined client scripts.
-
- 6. Set some kernel parameters.
-
- On most distributions I have checked this script is very well
- commented and it is possible for an experienced user to remove some
- lines that are not wanted or not applicable during a network boot.
- I 've also noticed that all programms started do not require the
- /usr directory to be mounted. If you are trying to netboot a host
- you must do the following modifications to this script:
-
-
-
- · Remove all entries that do fsck or initialise raid arrays, and add
- to the top of the script this command : mount -o remount,rw /
- because the client has to have rw access to the root directory when
- it boots.
-
- · Do not let the kernel deamon start until all partitions are mounted
-
- · Mount a swap partition. This is described later.
-
- · Start the portmapper. If your system has a specific directory for
- starting bootup scripts, place the portmapper startup script there
- giving it the highest priority possible, for example: ln -s
- /etc/rc.d/portmap /etc/rc.d/boot/S01portmap if you are using SuSE.
-
- · Place the NFS filesystem mounting script in the system specific
- directory for boot scripts with priority lower than the portmapper,
- for example ln -s /etc/rc.d/nfs /etc/rc.d/boot/S02nfs for SuSE.
-
- · Remove all entries that automount local partitions, and all entries
- that start an automounter deamon for RedHat.
-
-
- 3.2.1. How to setup a swap partition
-
- This is tricky business! Swapping over NFS is not allowed by the
- kernel and not functioning either. You cannot use swapon on files that
- are on an NFS mounted filesystem. We have to do some tricks to enable
- it:
-
- 1. Create the swap file. Its size can be variable but for a machine
- with 128 MB of RAM a swap size of 40-50 MB seems reasonable. The
- command to create the swap file is: dd if=/dev/zero of=/var/swap
- bs=1k count=Xk where X stands for the number of MB your swap should
- be. It is also a necessity to put the swap file under /var as long
- as it is mounted at boot.
-
- 2. Format the swap file using the mkswapfs command.
-
- 3. Initialise a loopback device using the swap file. The command is
- losetup /dev/loop0 /var/swap.
-
- 4. Mount the loopback device with the command mount /dev/loop0 swap.
-
- You have to initialise a swap partition at the very beginning of
- the boot process. So place commands 2-4 somewhere near to the top
- of the startup script. The first command is very time
- consuming,especially in the case of a loaded network so just copy a
- swap file in the base system and do not delete it when you create
- directories for each host.
-
-
- 3.2.2. Modifying /etc/fstab
-
- The /etc/fstabfile contains entries for automounting file systems at
- boot. In our case, we have to place the following lines at the end of
- it:
-
-
- server_IP:/usr/local/linux/base/usr /usr nfs nfsvers=3,wsize=2048,tcp 0 0
- server_IP:/usr/local/linux/base/opt /opt nfs nfsvers=3,wsize=2048,tcp 0 0
- server_IP:/usr/local/linux/base/lib/modules /lib/modules nfs nfsvers=3 wsize=2048,tcp 0 0
- fileserver_IP:/home /home nfs nfsvers=3,wsize=2048,tcp 0 0
-
-
-
- Also, do not forget to comment out lines that mount local partitions.
- Save this file as /etc/fstab.new because it should not be activated
- yet, as long as we have to boot the base system first.
-
- 3.2.3. Copying password files
-
- You must provide the system with to files to let the users perform a
- login. To do this just copy the files /etc/passwd and /etc/shadow from
- your file server to the base system. Notice that you have to do it
- every time you add a user to the system, or a user changes his/her
- password, so can best be done by creating a cron job.
-
-
- 3.3. Booting the base system
-
- To boot the base system we have to create a boot disk first. Go to
- the next section and create a boot disk as recommended. Please, change
- the 'append' line to this one:
-
-
- append init=/sbin/init root=/dev/nfs
- ip=X:Y:195.251.160.254:255.255.255.0:::'off'
- nfsroot=Y:/usr/local/linux/base vga=0x318
-
- (Of course, in a sigle line)
-
-
-
- where X stands for an unused IP address in your network and Y for the
- IP address of the NFS server. Of course, you have to export the
- /usr/local/linux/base directory from the NFS server with the
- rw,no_root_squash options. Now boot the base system. Everything
- should work OK, but I don' t think that there is a possibility that
- you succeeded from the first boot! There are many obscure points,
- that you have forgotten to edit or I have forgotten to mention.
-
-
- This is the standard method to boot the base system and to add
- programms or a new kernel to your installation. So backup the files
- you have edited as well as the boot disk image.
-
- After succeeding to boot the system, you are in a complete linux
- enviroment. Login as root and enjoy a first ride in your newly
- created system! Now comes the hard time... You have to disable some
- services that startup automatically and remove some programms not
- needed by the users.
-
- 3.4. Configuring the system
-
- Nearly all distributions start these services:
-
- · inetd, the Internet superdeamon responsible for starting other
- deamons like telnet, ftp etc.
-
- · syslogd, the logging deamon. Not needed on a diskless client not
- needed because all the modifications are done to files easyly
- replacable.
-
- · httpd, the apache webserver. Not needed for obvious reasons.
-
- · dhcpclient. Needed for automatic aquisition of an IP address. At
- out case, this is done by the kernel.
-
- · lpd, the line printer deamon. This is needed only when you have a
- printer connected to a host. In most cases, this is not needed.
- Also, according to your installation, there may be started sshd,
- nscd, cupsd and other network services not needed on clients. To
- disable these services, remove their entries from the runtime
- directory under /etc/rc.d/X. There is a more elegant way to do
- this under SuSE or RedHat, using Yast or Linuxconfig. For Yast, go
- to System administration ---> Change configuration file and using
- search locate the entries for every service you want to stop.
-
- Then, uninstall all these services from the base system. The only
- service that seems reasonable to me to be left running is the
- NameServer caching deamon, which is able to reduce network traffic a
- lot.
-
- Now, you have to edit some files:
-
- · /etc/resolv.conf Used to provide a nameserver. Add these entries:
- nameserver xxx.xxx.xxx.xxx and domain xxxxx , replacing x with the
- correct values.
-
- · /etc/hosts Used to match IP addresses to host names localy. Provide
- the basic servers' names of your network.
-
- · /etc/nntpserver Used to provide a news server. Just append the
- nameserver 's hostname.
-
- · /etc/fstab Restore the fstab.new file we have created earlier.
-
- 3.4.1. Configuring the language
-
- Perhaps, you do not leave in the US or the UK, like me, so you have to
- configure the language. This is simply done through the .profile
- file. Just add the following: export LANG="X"where X is your natural
- language. Then, download a console font which supports your codepage
- and set, with the help of Yast, the keyboard keymap. Copy .profile to
- /etc/skel of the file server or to all the users' home directories.
-
- 3.4.2. The X window system
-
- If you want to provide a working X enviroment for clients with
- different graphics hardware, you have to use the XFBDev server. If you
- followed the instructions on howto create a boot disk, you would now
- be in framebufer mode at 1024x768@16M colors, which is sufficient for
- use with X windows. Now, you have to configure the X server to load
- the framebuffer driver. SuSE provides an exellent tool for configuring
- X wherher it might be version 3 or 4. It is called sax for X 3.3.x and
- sax2 for X 4.x. To use XFBDev driver start sax with the -s XF86_FBDev
- option and configure the server according to your hardware. In case
- you do not use SuSE, most of the work must be done by hand. Create a
- basic /etc/X11/XF86Config file using xf86config4. Please choose
- entries that are as much as possible closer to your needs. Then edit
- the /etc/X11/XF86Config. This file is devided into sections that
- start with the keyword 'Section' and end with 'EndSection'. Do the
- following modifications:
-
- · Section "Files": Add the path to the direcory where you 've put
- your fonts.
-
- · Section "Module": Load the GLX module if you want REALLY SLOW Open
- GL graphics (Load glx)!
-
- · Section "InputDevice, Driver="mouse"": Add the following lines if
- you want to use a wheel mouse:
-
-
-
- Option "Buttons" "5"
- Option "ZAxisMapping" "4 5"
-
-
-
- · Section "Device": Replace everything with the following:
-
-
- BoardName "AutoDetected"
- Driver "fb"
- Identifier "Device[0]"
- VendorName "AutoDetected
-
-
-
- · Section "Modes": Replace everything with the following:
-
-
- Identifier "Modes[0]"
- Modeline "1024x768" 71.39 1024 1040 1216 1 400 768 768 776 802
-
-
-
- · Section "Screen": Replace everything with the following
-
-
- DefaultDepth 16
- SubSection "Display"
- Depth 16
- Modes "1024x768"
- EndSubSection
- Device "Device[0]"
- Identifier "Screen[0]"
- Monitor "Monitor[0]"
-
-
-
- · Section "ServerLayout": Replace everything with the following:
-
-
- Identifier "Layout[all]"
- InputDevice "Keyboard[0]" "CoreKeyboard"
- InputDevice "Mouse[1]" "CorePointer"
- Screen "Screen[0]"
-
-
-
- and then replace the first argument of the InputDevice directives with
- the identifiers which can be found earlier in the file.
-
- I thing that it should be a working configuration for framebuffer sys
- tems. For further reference take a look at the XF86Config and the
- xf86cfg4 man pages. You will find a working XF86Config file at
- Appendix C.
-
-
- 3.4.3. Configuring network access for KDE2
-
- KDE is the most extensible, configurable and internet enabled window
- manager available, even if we count some commercial ones that are
- proud of it! To download KDE, ftp to ftp.kde.org and get the rpms for
- your distribution. There, you can also find vanilla sources and other
- related projects.
-
- The main configuration to KDE is done through the K Control Center.
- There you can find options for configuring the fonts, colors,
- backgrounds etc. The most important thing you can configure is the
- LAN browsing deamon that KDE incorporates, lisa. There is also a
- readme file under \$KDE2ROOT/share/apps/lisa. After you configure
- lisa, you have to make it (or her?) start in the background every time
- the computer is started. Find the lisa 's configuration file under
- /root. Copy it under /etc. Aftewards, place the command lisa -c
- /etc/lisa.conf at the /etc/rc.d/boot.local file, or the similar for
- your installation. Now tell me, which is easiest to search a network
- Windows or Linux?
-
- If your users are coming from the Windows world, they are familiar to
- find programms at the damned 'Start' menu. To make their transition
- easy, edit the KDE menu with the Menu Editor programm and add or
- remove applications there. Then, copy the .kde2 directory from you
- directory to the /etc/skel directory of your file server. Every new
- account you create will have access to the menu (and the settings) you
- have created.
-
-
- 4. Preparing the boot disk
-
- To prepare a boot disk we just want a kernel, syslinux and a 1,44MB
- diskette. Syslinux is tiny boot loader, designed specifically to boot
- a kernel and pass some arguments through its command line using a
- diskette. As we will see it very easy to configure, too.
-
-
- 4.1. Building a kernel
-
- Always choose the newest kernel to build. As of this time of writing
- (Wed Sep 12 17:28:22 2001) the newest kernel is 2.4.9. Building an
- older kernel can only save you time updating the nesessary programms.
- Also, be sure you have the program versions described in
- /usr/src/linux/Documentation/Changes. It is a good idea to compile
- the kernel using the base system to be served. The kernel can be build
- according to your needs of drivers, but it must contain the following
- options:
-
- · Build in support for the cient 's network card (Network device
- support ---> Select your card driver).
-
- · Build in support for the BOOTP protocol (Networking options --->
- IP: kernel level autoconfiguration ---> IP: BOOTP support).
-
- · Build in support for NFS and root over NFS (File systems --->
- Network File Systems ---> NFS file system support and File systems
- ---> Network File Systems ---> NFS file system support ---> Root
- over NFS).
-
- · Build in support for loopback devices (Block devices ---> Loopback
- device support).
-
- Do not forget to compile in the VESA framebuffer driver. Then go on
- with the familiar kernel compilation routine. Unless you have
- build the kernel using the base system, copy all the modules
- created to the base/lib/modules directory of the exported directory
- structure. The new kernel resides at
- /usr/src/linux/arch/i386/boot.
-
- You also have to set the root device to your kernel. You have to use
- the rdev programm. Execute the following commands:
- mknod /dev/boot255 c 0 255
- rdev /path/to/kernel/file /dev/boot255
-
-
-
- 4.2. Creating the boot disk
-
- Now, we have to use the syslinux programm. Insert a disk into the
- first floppy drive and run:
-
-
- syslinux -s /dev/fd0
-
-
-
- Mount the floppy and notice that syslinux has written 2 files:
- syslinux.cfg and ldlinux.sys. The second is the boot loader
- executable. The syslinux.cfg is the programm configuration file. A
- typical structure for that file is the following:
-
-
- default linux
- append init=/sbin/init root=/dev/nfs
- ip=:195.251.160.10:195.251.160.254:255.255.255.0:::'bootp'
- nfsroot=195.251.160.10:/usr/local/linux/ws/\%s vga=0x318
-
- prompt 1
- timeout 30
- readinfo 2
-
-
-
- The default statment is the kernel name to be booted and the append is
- the command line to be passed to the kernel. Now, you have to copy the
- kernel you have created to the floppy and rename it to 'linux'.
-
-
- 4.3. The kernel command line
-
- To boot a diskless client, its kernel must have the following command
- line options:
-
- · init=/sbin/init: If your init programm is elsewhere just change the
- path.
-
- · root=/dev/nfs: An alias to say the kernel that it has to mount its
- root directory over nfs
-
- · ip: This command line option tells the kernel how to get it's IP
- address and which is the NFS server's address
-
- · nfsroot: Tells the kernel to mount this directory as its root. The
- % is an alias to the host 's IP address.
-
- · vga: If you want to be able to start X windows in framebuffer mode,
- switch to a framebuffer mode. The one given stands for 1024x768@16M
- colors.
-
- All these options are discussed in detail in
- /usr/src/linux/Documentation/nfsroot.txt. Read it and adjust the
- given command line to your needs.
-
-
- Now you have created the boot disk you are ready to test the system
- you have build. Start the NFS and BOOTP services and boot a client
- with the boot disk. No one has been able to do it from the first time.
- So go on to the next section!
-
-
- 5. The magic time
-
- In this section will be discused all the problems that you have and
- the changes that you propose to the installation. Please feel free to
- email me and ask about any difficult or not mentioned points in this
- document. My email is cs98011@icsd.aegean.gr
-
- Q: A DHCP is already running. How do I configure BOOTP, so as no
- interaction is made with the DHCP?
-
- A: This was the main problem I faced when I installed the system on a
- running network. DHCP and BOOTP use the same port. When a windows
- client boots, it issues a DHCP/BOOTP request to locate its IP (of
- course in case of dynamic IP). When the DHCP server responds, it also
- returns the IP's of DNS servers, print servers and Domain Controlers.
- My BOOTP server was responding faster than the Microsoft DHCP server,
- an so Windows clients were unable to locate their Domain controler.
- This resulted to users not being able to login! The solution described
- here was donated by D. Spinellis.
-
- Open the /usr/src/linux/net/ipv4 file. This is were all BOOTP
- autoconfiguration is done. Search for udph.source,udph.dest
- variables. You will see that they are set to the standard 67/68
- request/responce ports. Change BOTH values so they use an unused UDP
- port in your network. A good port pair that no application uses it is
- 967/968. Now, start your DHCPd with the -p 967 option. Everything must
- be working OK!
-
-
- 6. Other Stuff
-
-
- 6.1. Contributors
-
-
- · Diomidis Spinellis: Structure and typographical corrections, the
- DHCP/BOOTP conflict resolution.
-
- 6.2. Copyrights
-
- This document is GNU copylefted by Georgios Gousios
- .
-
- It is covered by the GNU documentation licence.
-
- Permission to use, copy, distribute this document for any purpose is
- hereby granted, provided that the author's / editor's name and this
- notice appear in all copies and/or supporting documents; and that an
- unmodified version of this document is made freely available. This
- document is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY, either expressed or implied. While every effort
- has been taken to ensure the accuracy of the information documented
- herein, the author / editor / maintainer assumes NO RESPONSIBILITY for
- any errors, or for any damages, direct or consequential, as a result
- of the use of the information documented herein
-
- 6.3. Contacting the author
-
- The author may be contacted via e-mail. For any change, question,
- error that must be corrected please feel free to contact me. For every
- contribution you make for this document, your name will be mentioned
- in the contributors section.
-
- 6.4. Changelog
-
-
- · v0.8, Thu May 24 17:37:13 2001 : First draft written.
-
- · v1.0, Fri May 25 01:36:25 2001 : The first version is complete (in
- HTML).
-
- · v1.05, Thu Jul 19 19:09:58 2001: Structure and typos corrections.
- Also, tranfered to LaTeX.
-
- · v1.1, Wed Sep 12 18:23:29 2001: Transfered to LinuxDoc SGML,
- donated to the LDP.
-
- 7. Appendix
-
-
- 7.1. Appendix A - A script for creating host directories
-
-
-
- #!/usr/bin/bash
- #This is a script for creating host directories using the
- #directory scheme illustrated before in this document.
- #It is written on Solaris and I did not test it on Linux.
- #Execute it at the ws directory.
- #Needs as input a file containing space separeted IP
- #addresses named addr, for example bash# ./script addr
- #This file must be like this: 195.251.160.10 195.251.160.11 195.251.160.13 ....
-
- echo "Creating the tar archive"; echo
-
- cd base
- tar cpf linux.tar ./bin ./dev ./etc ./lib ./sbin ./var
- mv linux.tar /usr/local/linux/ws/linux.tar
- cd ..
-
- echo "Creating host directories"; echo
-
- for addr in $(cat addr)
- do
- echo "Working on host $addr"
- mkdir $addr
- cd $addr
- echo " ---Creating nessesary directores"
- mkdir boot
- mkdir cdrom
- mkdir floppy
- mkdir home
- mkdir mnt
- mkdir opt
- mkdir proc
- mkdir root
- mkdir tmp
- mkdir usr
- echo " ---Extracting tar archive"
-
- ln -s ../linux.tar ./linux.tar
- tar xf linux.tar
- rm linux.tar
-
- echo " ---Removing unnessesary files"
- rm -R ./lib/modules/*
- rm -R ./var/yp
- rm -R ./var/X11R6/sax
- rm -R ./var/tmp
- rm -R ./var/state/dhcp
- rm -R ./var/squid
- rm -R ./var/run/*
- rm -R ./var/opt
- rm -R ./var/named
- rm -R ./var/mysql
- rm -R ./var/lib/amanda
- rm -R ./var/lib/codadmin
- rm -R ./var/lib/firewall
- rm -R ./var/lib/apsfilter
- rm -R ./var/lib/gdm
- rm -R ./var/lib/misc
- rm -R ./var/lib/nobody
- rm -R ./var/lib/pcmcia
- rm -R ./var/lib/pgsql
- rm -R ./var/lib/rpm/*
- rm -R ./var/lib/setup
- rm -R ./var/lib/wvdial
- rm -R ./var/lib/wwwrun
- rm -R ./var/lib/xdm
- rm -R ./var/lib/xkb
- rm -R ./var/lib/YaST/*
- rm -R ./var/lib/zope
- rm -R ./var/log/*
- rm -R ./var/cache/*
- rm -R ./var/games
- rm -R ./var/adm/*
-
- echo " ---Deciding the hostname"
- nslookup $addr |sed -n "s/^Name: *//p" >etc/HOSTNAME
- cd ..
- i=$(($i+1))
- echo
-
- done
- echo "Removing the tar archive"
- rm linux.tar
- echo
- exit 0
-
-
-
- 7.2. Appendix B - A script to create the dhcpd.conf file using arp
- watch
-
-
-
- #!/bin/bash
- #A script that starts arpwatch, pings a range of addresses and creates an
- #/etc/dhcpd.conf file from the output of arpwatch.
- #The arp.dat2dhcpd.conf programm is described later.
- #Do not forget to edit the i variable and the while statement to specify
- #the range of the addresses you want to ping
-
- i=128;
-
- echo "Starting arpwatch";echo
- arpwatch
-
- while [ "$i" -lt 253 ]
- do
- addr=195.251.160.$i
- echo "Now pinging $addr"
- ping -c 5 $addr >/dev/null
- i=$(($i+1))
- done
- echo
- exit
- killproc arpwatch
- echo "Creating /etc/dhcpd.conf"
- cat /var/lib/arpwatch/arp.dat |arp.dat2dhcpd.conf >/etc/dhcpd.conf
-
-
-
- 7.2.1. The arp.dat2dhcpd.conf script
-
-
-
- #!/usr/bin/perl -n
- ($ether, $ip,$stup1,$name) = split;
- if ($name eq "") {
- print "
- host host$i {
- hardware ethernet $ether;
- fixed-address $ip;
- }
- ";
- $i++;}
- else{
- print "
- host $name {
- hardware ethernet $ether;
- fixed-address $ip;
- }
- "}
-
-
-
- 7.3. Appendix C - A sample XF86Config file
-
-
-
- #This file should let X 4.0.1 work in 1024x768@16M colors
- #with the fbdev driver using the linux's framebuffer
- Section "Files"
- RgbPath "/usr/X11R6/lib/X11/rgb"
- FontPath "/usr/X11R6/lib/X11/fonts/75dpi:unscaled"
- FontPath "/usr/X11R6/lib/X11/fonts/local"
- FontPath "/usr/X11R6/lib/X11/fonts/misc:unscaled"
- FontPath "/usr/X11R6/lib/X11/fonts/100dpi:unscaled"
- FontPath "/usr/X11R6/lib/X11/fonts/Type1"
- FontPath "/usr/X11R6/lib/X11/fonts/URW"
- FontPath "/usr/X11R6/lib/X11/fonts/Speedo"
- FontPath "/usr/X11R6/lib/X11/fonts/misc"
- FontPath "/usr/X11R6/lib/X11/fonts/75dpi"
- FontPath "/usr/X11R6/lib/X11/fonts/100dpi"
- FontPath "/usr/X11R6/lib/X11/fonts/PEX"
- FontPath "/usr/X11R6/lib/X11/fonts/cyrillic"
- FontPath "/usr/X11R6/lib/X11/fonts/latin2/misc"
- FontPath "/usr/X11R6/lib/X11/fonts/latin2/75dpi"
- FontPath "/usr/X11R6/lib/X11/fonts/latin2/100dpi"
- FontPath "/usr/X11R6/lib/X11/fonts/latin7/75dpi"
- FontPath "/usr/X11R6/lib/X11/fonts/kwintv"
- FontPath "/usr/X11R6/lib/X11/fonts/truetype"
- FontPath "/usr/X11R6/lib/X11/fonts/uni"
- FontPath "/usr/X11R6/lib/X11/fonts/ucs/misc"
- FontPath "/usr/X11R6/lib/X11/fonts/ucs/75dpi"
- FontPath "/usr/X11R6/lib/X11/fonts/ucs/100dpi"
- FontPath "/usr/X11R6/lib/X11/fonts/xtest"
- EndSection
-
- Section "ServerFlags"
- AllowMouseOpenFail
- EndSection
-
- Section "Module"
- EndSection
-
- # This section is no longer supported
- # See a template below
- # Section "XInput"
- # EndSection
-
- Section "Keyboard"
- Protocol "Standard"
- XkbRules "xfree86"
- XkbModel "microsoft"
- XkbLayout "us"
- EndSection
-
- Section "Pointer"
- Protocol "PS/2"
- Device "/dev/psaux"
- SampleRate 60
- BaudRate 1200
- Buttons 5
- EndSection
-
- Section "Monitor"
- Identifier "Primary-Monitor"
- VendorName "Unknown"
- ModelName "Unknown"
- HorizSync 29-64
- VertRefresh 47-90
- Modeline "1400x1050" 59.93 1400 1416 1704 1816 1050 1050 1055 1097
- Modeline "1280x960" 59.90 1280 1296 1552 1664 960 960 965 1003
- Modeline "1600x1000" 59.90 1600 1616 1968 2080 1000 1000 1004 1044
- Modeline "1024x864" 59.89 1024 1040 1216 1328 864 864 870 902
- Modeline "800x600" 58.55 800 816 928 1040 600 600 608 626
- Modeline "1152x864" 59.99 1152 1168 1384 1496 864 864 870 902
- Modeline "1280x1024" 59.90 1280 1296 1552 1664 1024 1024 1029 1070
- Modeline "640x480" 37.44 640 656 720 832 480 480 486 501
- Modeline "1024x768" 59.89 1024 1040 1216 1328 768 768 774 802
- Modeline "1600x1200" 59.90 1600 1616 1968 2080 1200 1200 1204 1253
- EndSection
-
- Section "Device"
- Identifier "Primary-Card"
- VendorName "---AUTO DETECTED---"
- BoardName "---AUTO DETECTED---"
- EndSection
-
- Section "Screen"
- Driver "fbdev"
- Device "Primary-Card"
- Monitor "Primary-Monitor"
- DefaultColorDepth 16
- SubSection "Display"
- Depth 32
- Modes "default"
- EndSubSection
- SubSection "Display"
- Depth 24
- Modes "default"
- EndSubSection
- SubSection "Display"
- Depth 16
- Modes "default"
- Virtual 1024 768
- EndSubSection
- SubSection "Display"
- Depth 8
- Modes "default"
- EndSubSection
- EndSection
-
- Section "Screen"
- Driver "fbdev"
- Device "Primary-Card"
- Monitor "Primary-Monitor"
- DefaultColorDepth 16
- SubSection "Display"
- Depth 32
- Modes "default"
- EndSubSection
- SubSection "Display"
- Depth 24
- Modes "default"
- EndSubSection
- SubSection "Display"
- Depth 16
- Modes "default"
- Virtual 1024 768
- EndSubSection
- SubSection "Display"
- Depth 8
- Modes "default"
- EndSubSection
- EndSection
-
-Network Boot and Exotic Root HOWTO
-
-Brieuc Jeunhomme
-
-frtest
-
- bbp@via.ecp.fr
-
-
-Logilab S.A.
-
-Revision History
-Revision 0.3 2002-04-28 Revised by: bej
-Many feedback inclusions, added links to several projects
-Revision 0.2.2 2001-12-08 Revised by: dcm
-Licensed GFDL
-Revision 0.2.1 2001-05-21 Revised by: logilab
-Fixed bibliography and artheader
-Revision 0.2 2001-05-19 Revised by: bej
-Many improvements and included Ken Yap's feedback.
-Revision 0.1.1 2001-04-09 Revised by: logilab
-First public draft.
-Revision 0.1 2000-12-09 Revised by: bej
-Initial draft.
-
-
-This document explains how to quickly setup a linux server to provide what
-diskless linux clients require to get up and running, using an IP network. It
-includes data and partly rewritten text from the Diskless-HOWTO, the
-Diskless-root-NFS-HOWTO, the linux kernel documentation, the etherboot
-project's documentation, the linux terminal server project's homepage, and
-the author's personal experience, acquired when working for Logilab.
-Eventually this document may end up deprecating the Diskless-HOWTO and
-Diskless-root-NFS-HOWTO. Please note that you'll also find useful information
-in the From-PowerUp-to-bash-prompt-HOWTO and the Thin-Client-HOWTO, and the
-Claus-Justus Heine's page about NFS swapping.
-
------------------------------------------------------------------------------
-Table of Contents
-1. Introduction
- 1.1. What is this all about?
- 1.2. Thanks
- 1.3. Diskless booting advocacy
- 1.4. Requirements
- 1.5. Acknowledgements and related documentation
- 1.6. Feedback
- 1.7. Copyright Information
-
-
-2. Diskless booting operation overview
- 2.1. Obtaining IP parameters
- 2.2. Loading the kernel
- 2.3. Mounting the root filesystem
- 2.4. Terminating the boot process
-
-
-3. Building the kernel
- 3.1. When the root filesystem is on a ramdisk
-
-
-4. Daemons setup
- 4.1. NFS daemon
- 4.2. BOOTP daemon
- 4.3. TFTP
-
-
-5. Clients setup, creation of the root filesystem
- 5.1. Creating the first files and directories
- 5.2. The /var and /etc directories
- 5.3. Last details
- 5.4. Trial...
- 5.5. And Error!
-
-
-6. Several ways of obtaining the kernel
- 6.1. BOOTP or DHCP capable NICs
- 6.2. Kernel on a local floppy or hard drive
- 6.3. Bootloader without kernel on a local floppy or hard drive
- 6.4. Creating ROMs for the clients
- 6.5. Local CDROM
-
-
-7. How to create diskless MS-Windows stations?
-8. Troubleshooting, tips, tricks, and useful links
- 8.1. Transparently handling workstations'specific files
- 8.2. Reducing diskless workstations'memory usage
- 8.3. Swapping over NFS
- 8.4. Swapping over network block devices
- 8.5. Getting rid of error messages about /etc/mtab or unmounted
- directories on shutdown
- 8.6. Installing new packages on workstations
-
-
-A. Non-Volatile Memory chips
-B. Determining the size and speed of EPROMs to plug in a NIC
-C. Companies selling diskless computers
-References
-
-1. Introduction
-
-1.1. What is this all about?
-
-Recent linux kernels offer the possibility to boot a linux box entirely from
-network, by loading its kernel and root filesystem from a server. In that
-case, the client may use several ways to get the first instructions it has to
-execute when booting: home made eproms, special network cards implementing
-the RARP, BOOTP or DHCP protocols, cdroms, or bootloaders loaded from a boot
-floppy or a local hard drive.
------------------------------------------------------------------------------
-
-1.2. Thanks
-
-Logilab sponsored this HOWTO. Check their [http://www.logilab.org] website
-for new versions of this document. I also thank the etherboot, netboot, plume
-and linux terminal server project developers and webmasters, who made it
-really possible to boot a Linux worstation over a network.
-
-Very special thanks go to Ken Yap, member of the etherboot project, whose
-comments greatly helped to improve the quality of this document.
-
-I also thank Jerome Warnier, main developer of the plume project, Pierre
-Mondié, Kyle Bateman, Peter T. Breuer, Charles Howes, and Thomas Marteau for
-their comments and contributions.
------------------------------------------------------------------------------
-
-1.3. Diskless booting advocacy
-
-1.3.1. Buying is cheaper than building
-
-Sometimes, buying a diskless linux computer will be cheaper than building!
-Checkout the list of commercial sites given in appendix, which are selling
-diskless linux network cards and diskless computers. These companies do mass
-production of linux diskless computers selling millions of units and thereby
-reducing the cost per unit.
------------------------------------------------------------------------------
-
-1.3.2. Advantages of diskless computers
-
-Diskless computers will become more and more popular in the next years. They
-will be very successful because of the availability of very high-speed
-network cards at very low prices. Today 100 Megabit per second (12.5 MB per
-sec transfer rate) network cards are common and in about 1 to 2 years
-1000 MBit (125 MB per sec transfer rate) network cards will become very cheap
-and will be the standard.
-
-In near future, monitor manufacturers will place the CPU, NIC, RAM right
-inside the monitor to form a diskless computer. This eliminates the diskless
-computer box and saves space. The monitor will have outlet for mouse,
-keyboard, network RJ45 and power supply.
-
-The following are benefits of using diskless computers:
-
- * Total cost of ownership is very low in case of diskless computers. Total
- cost of ownership is cost of initial purchasing + cost of maintenance.
- The cost of maintenance is usually 3 to 5 times the cost of initial
- computer purchase and this cost is recurring year after year. In case of
- diskless computers, the cost of maintenance is completely eliminated.
-
- * All the backups are centralized at one single main server.
-
- * No need of UPS battery, air-conditioning, dust proof environment for
- diskless clients, only server needs UPS battery, A/C and dust proof
- environment.
-
- * A better protection from virus attack - Some computer virus cannot attack
- diskless computers as they do not have any hard disk. This kind of virus
- cannot do any damage to diskless computers. Only one single server box
- needs to be protected against virus attack. This saves millions of
- dollars for the company by avoiding installation of vaccines and cleaning
- the hard disks.
-
- * Servers can have large powerful/high performance hard disks, can optimize
- the usage of disk space via sharing by many diskless computer users.
- Fault tolerance of hard disk failure is possible by using RAID on main
- server.
-
- * On some installations: sharing of central server RAM memory by many
- diskless computer users. For example, if many users are running a web
- browser remotely on a server, then there will be only one copy of this
- web browser in its RAM.
-
- * Very few system administrators required to maintain central server.
-
- * Zero administration at diskless client side. Diskless computers are
- absolutely maintenance free and troublefree.
-
- * Long life of diskless clients.
-
- * Eliminates install/upgrade of hardware, software on diskless client side.
-
- * Eliminates cost of cdrom, floppy, tape drive, modem, UPS battery, printer
- parallel ports, serial ports etc...
-
- * Can operate in places like factory floor where a hard disk might be too
- fragile.
-
-
------------------------------------------------------------------------------
-1.4. Requirements
-
-1.4.1. Hardware requirements
-
-The most important thing in order to boot from network is to have an
-equipment which enables the stations to execute a bootloader, which will get
-the kernel on the server and launch it. Another solution is to use a device
-which will load a local kernel, which will mount the root filesystem on the
-server. There are several solutions: home made eproms containing the first
-instructions to execute when booting the station, boot with BOOTP/DHCP
-capable network adapters, or a local floppy, a tiny hard drive, or a cdrom to
-load the kernel. Note that some vendors also sell network booting capable
-stations: for instance, some Sun stations implement the BOOTP protocol.
-
-Other hardware requirements depend on the configuration you plan to use: on
-some sites, every application run by the stations is executed remotely on the
-server, this implies that a very high-performance server is required, but
-only light stations are required: depending on what they will have to do,
-80486 CPUs with 16 MB of RAM may be enough. On the other side, if application
-programs are really executed locally on the stations, the requirements for
-the stations depend completely on these applications. In that case, only a
-small server is required. A 80486 CPU with 32 MB of RAM will be sufficient
-for a small number of stations, but more memory will be necessary in very
-large installations with hundreds or thousands of machines. Note the server's
-CPU does not really matter for such an installation.
------------------------------------------------------------------------------
-
-1.4.2. Software requirements
-
-Linux kernel version 2.0 or above sources are required. All tools required to
-build a linux kernel are also necessary (see the linux kernel documentation
-for more information on this).
-
-A BOOTP daemon (a DHCP daemon may also do fine, but I won't explain how to
-configure this), a NFS daemon (if you want to mount the root filesystem on a
-remote server), are also required. We will also need a TFTP daemon if you
-plan to load the kernel remotely. At last, the mknbi utility provided with
-the [http://etherboot.sourceforge.net] etherboot distribution, and, if you
-use LanWorks EPROMs, like those included in the 3c905 3com ethernet adapter,
-you will also need the imggen utility, available at [http://www.ltsp.org/
-contrib/] http://www.ltsp.org/contrib/.
------------------------------------------------------------------------------
-
-1.5. Acknowledgements and related documentation
-
-This documentation has been written for experimented system administrators,
-who are already aware of linux fundamentals, like the use of grep, sed, and
-awk, basic shell programming, the init process and the boot scripts, kernel
-compilation, and NFS server configuration. Experience of kernel arguments
-passing should also help. Information on these subjects can be found
-respectively in the grep, sed, awk, and bash man/info pages, in the
-Bootdisk-HOWTO, the From-PowerUp-To-Bash-Prompt-HOWTO, the Kernel-HOWTO, the
-BootPrompt-HOWTO, the bootparam man page, the rdev man page, the NFS-HOWTO,
-and the exports manual page.
-
-There are many sources of information on network booting, but, and this is
-why I wrote this HOWTO, none describes all the existing ways of booting over
-a network, and much of them are specific to a way of operating. The most
-useful to me has been the documentation provided by the [http://www.ltsp.org]
-linux terminal server project, although I did not use the packages they
-recommend, and I have chosen to describe here how to proceed without these
-packages, because they configure things so that every application program is
-executed remotely on a server. Useful information can also be found on the
-[http://etherboot.sourceforge.net] etherboot project's homepage.
-
-At last, you can also find useful but succinct information in the kernel's
-source tree, in /usr/src/linux/Documentation, assuming your kernel source
-tree resides in /usr/src/linux.
------------------------------------------------------------------------------
-
-1.6. Feedback
-
-I will highly appreciate any feedback about this document. Please feel free
-to mail me at if you have any comment, correction, or
-suggestion. You may also use .
------------------------------------------------------------------------------
-
-1.7. Copyright Information
-
-This document is copyrighted (c) 2001 and is distributed under the terms of
-the GNU Free Documentation License. You should have received a copy along
-with it. If not, it is available from [http://www.fsf.org/licenses/fdl.html]
-http://www.fsf.org/licenses/fdl.html.
------------------------------------------------------------------------------
-
-2. Diskless booting operation overview
-
-Hey, you think it's time to start with the real stuff, right? Here we go.
------------------------------------------------------------------------------
-
-2.1. Obtaining IP parameters
-
-One could wonder how a station may boot over an IP network if it doesn't even
-know its own IP address. In fact, three protocols enable the client to obtain
-this information and some additional configuration parameters:
-
- * RARP: this is the simplest of these protocols. However I guess it does
- not enable the server to specify how the client should download the
- kernel, so we won't use it (In fact, there is a convention that uses the
- IP address of the workstation as filename, e.g. a client getting the
- address 192.168.42.12 by RARP might ask for /tftpboot/192.168.42.12 by
- TFTP, as the linux kernel does. The filename might also be the hex form
- of the IP address, this is implementation dependant, and is not
- mandatory.).
-
- * BOOTP: this protocol allows a server to provide the client (identified by
- its hardware MAC address) with much information, in particular its IP
- address, subnet mask, broadcast address, network address, gateway
- address, host name, and kernel loading path. This is the one we will use.
-
- * DHCP: this is an extension of BOOTP.
-
-
------------------------------------------------------------------------------
-2.2. Loading the kernel
-
-When the client has got its IP parameters, if the kernel is not on a local
-support (like a floppy, a cdrom, or a hard drive), the client will start to
-download it via TFTP. Its location is given by the BOOTP/DHCP server. A
-server (not necessarily the BOOTP/DHCP server) will also have to run a TFTP
-daemon for non local kernels. The kernel one obtains after compilation can
-not be used "as is" for BOOTP/DHCP operation, its binary image has to be
-modified with the mknbi utility (and then modified again with the imggen
-utility if you use LanWorks EPROMs). The mknbi utility should also be used to
-modify kernels that will be written in a ROM.
------------------------------------------------------------------------------
-
-2.3. Mounting the root filesystem
-
-After the kernel has started, it will try to mount its root filesystem. The
-location of this filesystem is also obtained through BOOTP/DHCP, and it is
-mounted via NFS. It means a client may use BOOTP twice for booting: the first
-time to get its kernel, and the second time to learn the location of the root
-filesystem (which may be on a third server).
-
-Another solution is to use a ramdisk as root filesystem. In this case, the
-ramdisk image is obtained with the kernel via TFTP.
------------------------------------------------------------------------------
-
-2.4. Terminating the boot process
-
-When the root filesystem is mounted, you can start breathing: you can at
-least use your swiss army knife with its sh, sed, and awk blades. In fact,
-you will have to customize the initialization scripts of the client's
-filesystem: for instance, you will have to remove all hard drive, floppy or
-cdrom related stuff from /etc/fstab (when your stations are not equipped with
-these devices), you may also have to inhibit swap partitions activation (note
-there is a way to swap over NFS or network block devices). You also will have
-to automagically generate all network configuration files at boot time if
-several clients use the same remote root filesystem.
------------------------------------------------------------------------------
-
-3. Building the kernel
-
-First of all, build a kernel for the clients. I suggest you build it on the
-server, this will be useful later for modules installation. Use a zImage to
-reduce its size. Include everything you need, but try to use as many modules
-as possible, because many BOOTP client implementations are unable to load
-very large kernels (at least on intel x86 architectures). Also include
-iramdisk support, NFS protocol support, root filesystem on NFS support,
-support for your NIC, kernel level IP autoconfiguration via BOOTP; do not use
-modules for these! Then, if you plan to use the same remote root filesystem
-for several clients, add support for ext2fs or some other filesystem and
-ramdisks (16 Megabytes ramdisks will do fine on most systems). You can then
-modify the kernel arguments as usual (see the BootPrompt-HOWTO for
-information on this topic), but you will have another opportunity to modify
-kernel arguments later.
-
-Then, if you plan to use BOOTP, copy the kernel zImage on the server. We will
-assume it resides in /tftpboot, its name is zImage, the name of the image you
-want to create from this zImage for BOOTP operation is kernel, and the nfs
-root filesystem will reside in /nfsroot.
-
-Issue the following commands on the server (the mknbi package should be
-installed):
- # cd /tftpboot
- # chmod 0555 zImage
- # chown root:root zImage
- # mknbi-linux zImage --output=kernel --rootdir=/nfsroot
-
-
-If you are using LanWorks EPROMs, also issue the following commands (you need
-the imggen utility):
- # mv -f kernel tmpkernel
- # imggen -a tmpkernel kernel
- # rm -f tmpkernel
-
-
-Your kernel is ready for BOOTP/DHCP/ROM operation. You of course don't need
-to do this if you plan to use a local drive.
------------------------------------------------------------------------------
-
-3.1. When the root filesystem is on a ramdisk
-
-It is possible to use a ramdisk for the root filesystem. In this case, the
-command used to modify the kernel's binary image is slightly different. If
-you choose to do so, you have to enable support for initial ramdisk (initrd),
-and you probably don't need NFS support, or you probably can compile it as a
-module.
-
-Its time to give an overview of what happens when you use initrd. The full
-documentation for this is in your kernel source tree, in the Documentation/
-initrd.txt file. I have to warn you I did never try this :).
-
-When initrd is enabled, the boot loader first loads the kernel and the inital
-ramdisk into memory. Then, the ramdisk is mounted read-write as root
-filesystem. The kernel looks for a /linuxrc file (a binary executable or a
-script beginning with #!). When /linuxrc terminates, the traditionnal root
-filesystem is mounted as /, and the usual boot sequence is performed. So, if
-you want to run your box entirely from ramdisk, you just have to create a
-link from /linuxrc to /sbin/init, or to write there a shell script to perform
-any action you like, and then shutdown the computer.
-
-After the kernel has been compiled, you have to build a root filesystem for
-your installation. This is explained in the "Clients setup, creation of the
-root filesystem" section. I will assume here that this is already done and
-that the root filesystem for your clients temporarily resides in /tmp/rootfs.
-You now have to create a ramdisk image. A simple way to do so is the
-following:
-
- * Make sure the computer you are working on has support for ramdisks and
- has such a device (/dev/ram0).
-
- * Create an empty filesystem with the appropriate size on this ramdisk:
- # mke2fs -m0 /dev/ram0 300
-
-
- * Mount it somewhere:
- # mount -t ext2 /dev/ram0 /mnt
-
-
- * Copy what you need for your new root filesystem, and create your future /
- linuxrc if you did not create it in /tmp/rootfs/linuxrc:
- # cp -a /tmp/rootfs/* /mnt
-
-
- * Unmount the ramdisk:
- # umount /mnt
-
-
- * Save the ramdisk image to some file and free it:
- # dd if=/dev/ram0 of=initrd bs=1024 count=300
- # freeramdisk /dev/ram0
-
-
-
-What was toled above about LanWorks PROMs is also true if you use initrd.
-
-Then, you have to modify the kernel image, as was told above, with the
-mknbi-linux utility. Its invocation will slightly differ from the above,
-though (I will assume your just compiled zImage resides in /tftpboot/zImage
-and your initial ramdisk image resides in /tmp/initrd):
- # cd /tftpboot
- # chmod 0555 zImage
- # chown root:root zImage
- # rdev zImage /dev/ram0
- # mknbi-linux zImage --output=kernel --rootdir=/dev/ram0 /tmp/initrd
-
------------------------------------------------------------------------------
-
-4. Daemons setup
-
-4.1. NFS daemon
-
-Just export the directory in which the client's root filesystem will reside
-(see the exports manpage for more information about this topic). The simplest
-is to export it no_root_squash and rw, but a perfect setup would export most
-of the root filesystem root_squash and ro, and have separate lines in the /
-etc/exports for directories which really require no_root_squash and/or rw.
-Just start with everything rw and no_root_squash, the fine tuning will be
-done later.
-
-Of course, you don't need any NFS server at all if you plan to run your
-clients entirely from ramdisk.
------------------------------------------------------------------------------
-
-4.2. BOOTP daemon
-
-I assume you have installed the bootpd package. The default configuration
-file is /etc/bootptab, and its syntax is detailed in the bootptab manpage.
-Let's create it.
-
-First, open as root your favourite text editor. It is vim. Yes, it is. If it
-is not, it has to become. Now, enter the following lines (they are the
-default attributes). All the attributes you give here and do not override in
-a machine's specific attributes list will be given to clients):
- .default\
- :sm=your subnet mask\
- :ds=the IP address of your DNS server\
- :ht=ethernet\
- :dn=your domain name\
- :gw=the IP address of your gateway\
- :sa=the IP address of the TFTP server\
- :bf=path to find the kernel image\
- :rp=path of the root filesystem\
- :hn
-
-Of course, not all these parameters are required, this depends on your
-network configuration and BOOTP implementations, but these will work in most
-cases.
-
-Then, add an entry per client in your network. An entry should look like
-this:
- dns of the client\
- :ha=MAC address of the client\
- :ip=IP address of the client
-
-The MAC address above is the hexadecimal hardware address of the client
-without the ':' characters.
-
-Here is a sample /etc/bootptab file:
- .default\
- :sm=255.255.0.0\
- :ds=192.168.0.2\
- :ht=ethernet\
- :dn=frtest.org\
- :gw=192.168.0.1\
- :sa=192.168.0.2\
- :bf=/tftpboot/kernel\
- :rp=/nfsroot\
- :hn
-
- foo\
- :ha=001122334455\
- :ip=192.168.2.12
-
- bar\
- :ha=00FFEEDDCCBB\
- :ip=192.168.12.42\
- :ds=192.168.2.42
-
-
-Then, run the bootpd daemon with the bootpd -s command (it is also a good
-idea to add it to your startup scripts), or add the following line to your /
-etc/inetd.conf:
- bootps dgram udp wait root /usr/sbin/tcpd bootpd -i -t 120
-
-
-If you want to test the BOOTP server, add an entry to your /etc/bootptab and
-use the bootptest program.
------------------------------------------------------------------------------
-
-4.3. TFTP
-
-Setting up the TFTP daemon is not the hard part: just install the tftpd
-package if you have one, and add the following line to your /etc/inetd.conf
-(again, I assume /tftpboot is the directory where the kernel image resides):
- tftp dgram udp wait root /usr/sbin/tcpd in.tftpd /tftpboot
-
-Don't forget to chmod 555 the /tftpboot directory, as most TFTP servers won't
-send the files if they are not world readable.
-
-You should be aware of the limitations implied by running the TFTP daemon
-from the inetd. Most inetd's will shutdown a service if it is spawned to
-frequently. So if you have many clients, you should look for another inetd
-like xinetd, or run a standalone TFTP daemon.
-
-Now you have properly setup all daemons, you can restart the inetd and take a
-coffee. Don't forget to tell everyone the server setup is over, so you think
-you're a hero before you start building the root filesystem for the clients.
------------------------------------------------------------------------------
-
-5. Clients setup, creation of the root filesystem
-
-Tired? No you're not. Remember you're a hero. Here comes the tricky part. We
-will (err... you will) build the client's root filesystem. This shouldn't be
-very hard, but you probably will have to use trial and error.
-
-The simplest way to create a root filesystem is to use an already working
-filesystem and customize it for the needs of diskless operation. Of course,
-you can also build one by hand (like in the good old times) if you like:=),
-but I won't explain this here.
------------------------------------------------------------------------------
-
-5.1. Creating the first files and directories
-
-First, cd to your future station's root directory. You can safely create the
-future /home directory with the mkdir command, or by copying it from anywhere
-you want (you can use cp -a to do a recursive copy preserving owners, groups,
-symlinks, and permissions). Same thing for the future /mnt, /root, /tmp
-(don't forget to chmod 0 it, this is only a mount point for the actual /tmp
-we will use, because each workstation needs to have its own /tmp). Then, copy
-some existing /bin, /sbin, /boot, and /usr into this future root directory
-(use cp -a). You can create the /proc directory with mkdir, and chmod 0 it.
-Note some applications need write access to their user's home directory.
-
-The /lib directory can be safely copied from somewhere else, but you will
-have to put the proper modules in it. To do so, use the following commands
-(assuming you have compiled the kernel for your clients on the server in /usr
-/src/linux, and the root filesystem will reside in /nfsroot):
- # cd /usr/src/linux
- # make modules_install INSTALL_MOD_PATH=/nfsroot
-
-
-Don't forget to put the System.map file in /nfsroot/boot. A first problem we
-will have to fix is that, depending on your configuration, your system may
-try to run fsck on the root filesystem at boot time. It shouldn't if there is
-no hard drive in the box. Most distributions will also skip this fsck if they
-find a fastboot file in the root directory. So, issue the following commands
-if you do not plan to mount any hard drive:
- # cd /nfsroot
- # touch fastboot
- # chmod 0 fastboot
-
-Another method is tell fsck that checking a NFS filesystem always succeeds:
- # cd /nfsroot/sbin
- # ln -s ../bin/true fsck.nfs
-
-
-The /dev directory can also be safely copied from another place into /
-nfsroot. But permissions and symlinks have to be preserved, so use cp -a.
-Another solution is to use kernel 2.2.x devfs feature, which will reduce
-memory consumption and improve performance, but the drawback of this method
-is that all symlinks created in /dev will be lost. The point to remember is
-that each workstation needs to have its own /dev, so you will have to copy it
-on a ramdisk if you plan to use several clients and not to use devfs.
------------------------------------------------------------------------------
-
-5.2. The /var and /etc directories
-
-We will use ramdisks for these directories, because each client needs to have
-its own one. But we still need them at the beginning to create their standard
-structure. Note you are not required to do so if you use a single client. So
-copy these directories (cp -a) from another place into /nfsroot. Then you can
-make some cleanup in /var: you can remove everything in /nfsroot/var/log and
-/nfsroot/var/run. You also probably can remove everything in /nfsroot/var/
-spool/mail, if you plan to export it via NFS. You also will have to remove
-the files containing host specific information in /nfsroot/etc to build them
-on the fly during the boot process.
-
-The startup scripts will have to be customized in order to mount some parts
-of the filesystem: the /dev directory, if you don't use devfs, the /tmp, the
-/var, and the /etc directories. Here is some code which will achieve this:
- # this part only if you don't use devfs
- mke2fs -q -i 1024 /dev/ram0 16384
- mount -n -t ext2 -o rw,suid,dev,exec, \
- async,nocheck /dev/ram0 /dev
- # this part for everyone
- mke2fs -q -i 1024 /dev/ram1 16384
- mount -n -t ext2 -o rw,suid,dev,exec, \
- async,nocheck /dev/ram1 /tmp
- chmod 1777 /tmp
- cp -a /etc /tmp
- mke2fs -q -i 1024 /dev/ram2 16384
- mount -n -t ext2 -o rw,suid,dev,exec, \
- async,nocheck /dev/ram2 /etc
- find /tmp/etc -maxdepth 1 -exec cp -a '{}' /etc ';'
- mount -f -t ext2 -o rw,suid,dev,exec, \
- async,nocheck,remount /dev/ram2 /etc
- mount -f -o remount /
- cp -a /var /tmp
- mke2fs -q -i 1024 /dev/ram3 16384
- mount -t ext2 -o rw,suid,dev,exec, \
- async,nocheck /dev/ram3 /var
- find /tmp/var -maxdepth 1 -exec cp -a '{}' /var ';'
-
-
-If you plan to use more than a single client, you will also have to change
-files dynamically at boot time in /etc: the files which contain the IP and
-hostname of the client. These files depend on your distribution, but you will
-easily find them with a few greps. Just remove client-specific information
-from them, and add code into your startup files to generate this information
-again at boot time but only once the new /etc has been mounted on the
-ramdisk! A way to obtain your IP address and hostname at bootup is the
-following (if you have the bootpc package installed on the
-workstations'filesystem):
- IPADDR="$(bootpc | awk '/IPADDR/ \
- {
- match($0,"[A-Za-z]+")
- s=substr($0,RSTART+RLENGTH)
- match(s,"[0-9.]+")
- print substr(s,RSTART,RLENGTH)
- }
- ')"
-
- HOST="$(bootpc | awk '/HOSTNAME/ \
- {
- match($0,"[A-Za-z]+")
- s=substr($0,RSTART+RLENGTH)
- match(s,"[A-Za-z0-9-]+")
- print substr(s,RSTART,RLENGTH)
- }')"
-
- DOMAIN="$(bootpc | awk '/DOMAIN/ \
- {
- match($0,"[A-Za-z]+")
- s=substr($0,RSTART+RLENGTH)
- match(s,"[A-Za-z0-9-.]+")
- print substr(s,RSTART,RLENGTH)
- }')"
-
-This is a complicated solution, but I guess it should work on most sites. The
-IP address can alternatively be obtained with the output of ifconfig and the
-hostname can be obtained from the output of the host command, but this is not
-portable, because these outputs differ from system to system depending on the
-distribution you are using, and the locales settings.
-
-Then, the hostname should be set with the hostname $HOSTNAME command. When
-this is done, it is time to generate on the fly the configuration files which
-contain the IP address or the hostname of the client.
------------------------------------------------------------------------------
-
-5.3. Last details
-
-Now, it's time to do the fine tuning of the client. As /var will be mounted
-on a ramdisk (unless you have a single client), you will have to send the
-logs to a logs server if you want to keep them. One way to do that is to
-delete the /nfsroot/etc/syslog.conf file and replacing it by the following
-file (see man syslog.conf for details):
- *.* /dev/tty12
- *.* @dns or IP of the logs server
-
-If you do so, the logs server will have to run syslogd with the -r option
-(see the syslogd manual page).
-
-If you use logrotate and you have done the preceding operation, you should
-replace the logrotate configuration file (/etc/logrotate.conf on most boxes)
-by an empty file:
- # rm -f /etc/logrotate.conf
- # touch /etc/logrotate.conf
-
-If you don't use it, just remove the logs rotation scripts from the crontab,
-and as you no longer have log files in /var/log, put an exit 0 at the
-beginning of your logs rotation scripts.
-
-In the /nfsroot/etc/fstab file, remove anything related to the hard drive,
-floppy disk reader, or cdrom if you don't have such devices on your
-workstations. Add an entry for the /var/spool/mail directory, which should be
-exported by the server through NFS or any other network filesystem. You
-probably also want to put an entry for the /home directory in this file.
-
-You can also comment the lines running newaliases, activating swap, and
-running depmod -a and remove the /nfsroot/etc/mtab file. Comment out the line
-(s) removing /fastboot, /fsckoptions, and /forcefsck in your startup scripts.
-Also remove or comment any line in the startup scripts that would try to
-write on the root filesystem except for really necessary writes, which should
-all be redirected to some ramdisk location if you use several clients.
------------------------------------------------------------------------------
-
-5.4. Trial...
-
-Time has come for a small trial. MAKE A BACKUP OF YOUR NEWLY CREATED /
-nfsroot. tar -cvvIf should do fine. Take a minute to verify we didn't forget
-anything. Try to boot a client.
------------------------------------------------------------------------------
-
-5.5. And Error!
-
-Look carefully at the client's screen during the boot process. Oh, I didn't
-tell you to connect a screen... Run, forest! Run an get one. You will
-probably see some error messages. Fix the problems, and make frequent backups
-of your /nfsroot. One day, the client will boot properly. This day, you will
-have to fix errors occurring during shutdown;=P.
------------------------------------------------------------------------------
-
-6. Several ways of obtaining the kernel
-
-We have spoken so far about the client and server's configuration for
-operation after the BOOTP request has been issued by the client, but the
-first problem is that most computers are not able to behave as BOOTP clients
-by default. We will see in this section how to fix this.
------------------------------------------------------------------------------
-
-6.1. BOOTP or DHCP capable NICs
-
-This is the most simple case: some network cards provide a supplement to the
-BIOS, containing a BOOTP or DHCP client, so just setup them for BOOTP or DHCP
-operation in the BIOS, and you're done.
------------------------------------------------------------------------------
-
-6.2. Kernel on a local floppy or hard drive
-
-These cases are also quite simple: the kernel is loaded from a local drive,
-and all the kernel has to do is to obtain its network parameters from BOOTP,
-and mount its root filesystem over NFS; this should not cause any problem. By
-the way, a local hard drive is a good place to leave a /var, /tmp, and a /
-dev...
-
-If you have a local hard drive, all you have to do is to use lilo or your
-favourite boot loader as usual. If you use a floppy, you can use a bootloader
-or simply write the kernel on the floppy: a kernel is directly bootable.This
-enables you to use a command like the following:
- # dd if=zImage of=/dev/fd0 bs=8192
-
-
-However, Alan Cox told in a linux-kernel thread that this feature of the
-linux kernel will be removed sooner or later, you thus will have to use a
-bootloader even on floppies some day. I know this still works with 2.4.11
-kernels, but support seems to have been removed in the 2.4.13 version. See
-the sixth chapter of the [http://www.tldp.org/HOWTO/Bootdisk-HOWTO/
-index.html] boot-disk-HOWTO for this topic.
------------------------------------------------------------------------------
-
-6.3. Bootloader without kernel on a local floppy or hard drive
-
-Certain bootloaders are network aware, you may thus use them to download the
-kernel image from the network. Some of them are listed below:
-
- * [http://netboot.sourceforge.net] netboot, a bootloader dedicated to
- network boot.
-
- * [http://www.gnu.org/software/grub/] GRUB, the GNU project's GRand Unified
- Bootloader, which is a very general purpose bootloader.
-
-
------------------------------------------------------------------------------
-6.4. Creating ROMs for the clients
-
-Many network cards include a slot in which one can insert an EPROM with
-additional BIOS code. This enables one to add, for instance, BOOTP
-capabilities to the BI0S. To do so, you will first have to find how to enable
-the EPROM socket. You may need a jumper or a special software to do so. Some
-cards like the 3Com 905B have slots for EEPROMs which enable one to change
-the software in the EEPROM in place. In appendix, you'll find the information
-about EPROM and various types of memory chips.
-
-For a list of EPROM burner manufacturers visit the Yahoo site and go to
-[http://dir.yahoo.com/Business_and_Economy/Companies/Computers/Hardware/
-Peripherals/Device_Programmers/] economy->company->Hardware->Peripherals->
-Device programmers or check out the old Diskless-HOWTO List of EPROM burner
-manufacturers section.
-
-If you choose to create your own ROMS, you will have to load a BOOTP or DHCP
-capable software in the ROM, and then, you will be in the case of BOOTP or
-DHCP capable NICs described above.
-
-You will also need to find the proper EPROM size and speed for your NIC. Some
-methods to do so are provided in appendix, because the NICs manufacturers
-often do not provide this information.
------------------------------------------------------------------------------
-
-6.4.1. LanWorks BootWare PROMs
-
-This information may save you time. In order to make LanWorks BootWare(tm)
-PROMs to correctly start up a linux kernel image, the "bootsector" part of
-the image must be modified so as to enable the boot prom to jump right into
-the image start address. The net-bootable image format created by netboot/
-etherboot's `mknbi-linux' tool differs and will not run if used with BootWare
-PROMs.
-
-A modified bootsector together with a Makefile to create a BootWare-bootable
-image after kernel compilation can be found at:
-
- * Bwimage package: [ftp://ftp.ipp.mpg.de/pub/ipp/wls/linux/bwimage-0.1.tgz]
- ftp://ftp.ipp.mpg.de/pub/ipp/wls/linux/bwimage-0.1.tgz
-
- * See also [http://www.patoche.org/LTT/net/00000096.html] http://
- www.patoche.org/LTT/net/00000096.html
-
- * LanWorks BootWare Boot ROMs: [http://www.3com.com/lanworks] http://
- www.3com.com/lanworks
-
-
-Refer to the README file for installation details. Currently, only
-"zImage"-type kernels are supported. Unfortunately, kernel parameters are
-ignored.
-
-This section was initially written by Jochen Kmietsch for the Diskless-HOWTO,
-email to: for any questions.
------------------------------------------------------------------------------
-
-6.5. Local CDROM
-
-This section was originally written by Hans de Goede <
-j.w.r.degoede@et.tudelft.nl> for the Diskless-root-NFS-HOWTO. I modified it
-slightly in order to reflect some differences between this document and the
-Diskless-root-NFS-HOWTO.
-
-Much of the above also goes for booting from cdrom. Why would one want to
-boot a machine from cdrom? Booting from cdrom is interesting everywhere one
-wants to run a very specific application, like a kiosk, a library database
-program or an internet cafe, and one doesn't have a network or a server to
-use a root over nfs setup.
------------------------------------------------------------------------------
-
-6.5.1. Creating a test setup
-
-Now that we know what we want to do and how, it's time to create a test
-setup:
-
- * For starters just take one of the machines which you want to use and put
- in a big disk and a cd burner.
-
- * Install your linux of choice on this machine, and leave a 650 MB
- partition free for the test setup. This install will be used to make the
- iso image and to burn the cd's from, so install the necessary tools. It
- will also be used to restore any booboo's which leave the test setup
- unbootable.
-
- * On the 650 mb partition install your linux of choice with the setup you
- want to have on the cd, this will be the test setup.
-
- * Boot the test setup.
-
- * Compile a kernel with isofs and cdrom support compiled in.
-
- * Configure the test setup as described above with the root filesystem
- mounted read only.
-
- * Verify that the test setup automagically boots and everything works.
-
- * Boot the main install and mount the 650 MB partition on /test of the main
- install.
-
- * Put the following in a file called /test/etc/rc.d/rc.iso, this file will
- be sourced at the beginning of rc.sysinit to create /var:
- #/var
- echo Creating /var ...
- mke2fs -q -i 1024 /dev/ram1 16384
- mount /dev/ram1 /var -o defaults,rw
- cp -a /lib/var /
-
-
- * Edit /test/etc/rc.sysinit, comment the lines where the root is remounted
- rw, and add the following 2 lines directly after setting the PATH:
- #to boot from cdrom
- . /etc/rc.d/rc.iso
-
-
- * Copy the following to a script and execute it to make a template for /var
- and create /tmp and /etc/mtab links.
- #!/bin/sh
- echo tmp
- rm -fR /test/tmp
- ln -s var/tmp /test/tmp
-
- ###
- echo mtab
- touch /test/proc/mounts
- rm /test/etc/mtab
- ln -s /proc/mounts /test/etc/mtab
-
- ###
- echo var
- mv /test/var/lib /test/lib/var-lib
- mv /test/var /test/lib
- mkdir /test/var
- ln -s /lib/var-lib /test/lib/var/lib
- rm -fR /test/lib/var/catman
- rm -fR /test/lib/var/log/httpd
- rm -f /test/lib/var/log/samba/*
- for i in `find /test/lib/var/log -type f`; do
- cat /dev/null > $i;
- done
- rm `find /test/lib/var/lock -type f`
- rm `find /test/lib/var/run -type f`
-
-
-
- * Remove the creation of /etc/issue* from /test/etc/rc.local: it will only
- fail.
-
- * Now boot the test partition again, it will be read only just like a
- cdrom. If something doesn't work reboot to the working partition fix it,
- try again etc. Or you could remount / rw, fix it, then reboot straight
- into to test partition again. To remount / rw type:
- # mount -o remount,rw /
-
-
-
------------------------------------------------------------------------------
-6.5.2. Creating the CD
-
-If you need more information than you can find below, please refer to the
-CD-Writing-HOWTO.
------------------------------------------------------------------------------
-
-6.5.2.1. Creating a boot image
-
-First of all, boot into the working partition. To create a bootable cd we'll
-need an image of a bootable floppy. Just dd-ing a zImage doesn't work since
-the loader at the beginning of the zimage doesn't seem to like the fake
-floppydrive a bootable cd creates. So we'll use syslinux instead.
-
- * Get boot.img from a redhat cd.
-
- * Mount boot.img somewhere through loopback by typing:
- # mount boot.img somewhere -o loop -t vfat
-
-
- * Remove everything from boot.img except for ldlinux.sys and syslinux.cfg.
-
- * Cp the kernel-image from the test partition to boot.img.
-
- * Edit syslinux.cfg so that it contains the following, of course replace
- zImage by the appropriate image name:
- default linux
-
- label linux
- kernel zImage
- append root=/dev/
-
-
-
- * Umount boot.img:
- # umount somewhere
-
-
- * If your /etc/mtab is a link to /proc/mounts, umount won't automagically
- free /dev/loop0 so free it by typing:
- # losetup -d /dev/loop0
-
-
-
------------------------------------------------------------------------------
-6.5.2.2. Creating the iso image
-
-Now that we have the boot image and an install that can boot from a readonly
-mount it's time to create an iso image of the cd:
-
- * Copy boot.img to /test
-
- * Cd to the directory where you want to store the image and make sure it's
- on a partition with enough free space.
-
- * Now generate the image by typing:
- # mkisofs -R -b boot.img -c boot.catalog -o boot.iso /test
-
-
-
------------------------------------------------------------------------------
-6.5.2.3. Verifying the iso image
-
- * Mounting the image through the loopbackdevice by typing:
- # mount boot.iso somewhere -o loop -t iso9660
-
-
- * Umount boot.iso:
- # umount somewhere
-
-
- * If your /etc/mtab is a link to /proc/mounts umount won't automagically
- free /dev/loop0 so free it by typing:
- # losetup -d /dev/loop0
-
-
-
------------------------------------------------------------------------------
-6.5.2.4. Writing the actual CD
-
-Assuming that you've got cdrecord installed and configured for your cd-writer
-type:
- # cdrecord -v speed= dev=