LDP
/
LDP
mirror of https://github.com/tLDP/LDP
0
1
Fork 0
Code Releases Activity

original SGML files found in output directory

This commit is contained in:
Martin A. Brown 2016-03-25 15:44:21 -07:00
parent a961647d66
commit 568ccc1088
16 changed files with 18937 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2278
LDP/retired/3Dfx-HOWTO.sgml Normal file
View File

File diff suppressed because it is too large Load Diff

1211
LDP/retired/Beowulf-HOWTO.sgml Normal file
View File

File diff suppressed because it is too large Load Diff

630
LDP/retired/IP-Subnetworking.sgml Normal file
View File

@ -0,0 +1,630 @@
<!doctype linuxdoc system>
<article>
<!-- Title information -->
<title>IP Sub-Networking Mini-Howto
<author>Robert Hart, <tt/hartr@interweft.com.au/
<date>v1.1, 30 August 2001
<!-- correct typos reported by users, 30 August 2001 -->
<!-- Greg Ferguson / linux-howto@metalab.unc.edu -->
<abstract>
This document describes why and how to subnetwork an IP network - that
is using a single A, B or C Class network number to function correctly on
several interconnected networks. </abstract>
<!-- Copyright 1997, Robert Hart -->
<sect>Copyright
<p>
This document is distributed under the terms of the GNU Public License (GPL).
<p>
This document is directly supported by InterWeft IT Consultants
(Melbourne, Australia).
<p>
The latest version of this document is available at the InterWeft WWW
site at <url url="http://www.interweft.com.au/" name="InterWeft IT
Consultants"> and from <url url="http://sunsite.unc.edu/LDP" name="The
Linux Documentation Project">.
<sect>Introduction
<p>
With available IP network numbers rapidly becoming an endangered
species, efficient use of this increasingly scarce resource is
important.
<p>
This document describes how to split a single IP network number up so
that it can be used on several different networks.
<p>
This document concentrates on C Class IP network numbers - but the
principles apply to A and B class networks as well.
<sect1>Other sources of information
<p>
There are a number of other sources of information that are of
relevance for both detailed and background information on IP numbers.
Those recommended by the author are:-
<itemize>
<item><url url="http://sunsite.unc.edu/LDP/LDP/nag/nag.html" name="The
Linux Network Administrators Guide">.
<item><url url="http://linuxwww.db.erau.edu/SAG/" name="The Linux System
Administration Guide">.
<item><url url="http://www.ora.com/catalog/tcp/noframes.html"
name="TCP/IP Network Administration by Craig Hunt, published by O'Reilly
and Associates">.
</itemize>
<sect>The Anatomy of IP numbers
<p>
Before diving into the delight of sub-networking, we need to establish
some IP number basics.
<sect1>IP numbers belong to Interfaces - <bf/NOT/ hosts!
<p>
First of all, let's clear up a basic cause of misunderstanding - IP
numbers are <bf/not/ assigned to hosts. IP numbers are assigned to
network interfaces on hosts.
<p>
Eh - what's that?
<p>
Whilst many (if not most) computers on an IP network will possess a
single network interface (and have a single IP number as a consequence),
this is not the only way things happen. Computers and other devices can
have several (if not many) network interfaces - and each interface has
its own IP number.
<p>
So a device with 6 active interfaces (such as a router) will have 6 IP
numbers - one for each interface to each network to which it is connected. The
reason for this becomes clear when we look at an IP network!
<p>
Despite this, most people refer to <em/host addresses/ when referring to an
IP number. Just remember, this is simply shorthand for <em/the IP number
of this particular interface on this host/. Many (if not the majority)
of devices on the Internet have only a single interface and thus a
single IP number.
<sect1>IP Numbers as &dquot;Dotted Quads&dquot;
<p>
In the current (IPv4) implementation of IP numbers, IP numbers consist
of 4 (8 bit) bytes - giving a total of 32 bits of available information.
This results in numbers that are rather large (even when written in
decimal notation). So for readability (and organisational reasons) IP
numbers are usually written in the 'dotted quad' format. The IP number
<tscreen><verb>
192.168.1.24
</verb></tscreen>
is an example of this - 4 (decimal) numbers separated by (.) dots.
<p>
As each one of the four numbers is the decimal representation of an 8
bit byte, each of the 4 numbers can range from 0 to 255 (that is take on
256 unique values - remember, zero is a value too).
<p>
In addition, part of the IP number of a host identifies the network on
which the host resides, the remaining 'bits' of the IP number identify
the host (oops - network interface) itself. Exactly how many bits are
used by the network ID and how many are available to identify hosts
(interfaces) on that network is determined by the network 'class'.
<sect1>Classes of IP Networks
<p>
There are three classes of IP numbers
<itemize>
<item>Class A IP network numbers use the leftmost 8 bits (the leftmost
of the dotted quads) to identify the network, leaving 24 bits (the
remaining three dotted quads) to identify host interfaces on that
network.<newline>
Class A addresses <bf/always/ have the leftmost bit of the leftmost
byte a zero - that is a decimal value of 0 to 127 for the first dotted
quad. So there are a maximum of 128 class A network numbers
available, with each one containing up to 33,554,430 possible
interfaces.
<newline><newline>
However, the networks 0.0.0.0 (known as the default route) and 127.0.0.0
(the loop back network) have special meanings and are not available for
use to identify networks. So there are only 126 <em/available/ A class
network numbers.
<item>Class B IP network numbers use the leftmost 16 bits (the leftmost two
dotted quads) to identify the network, leaving 16 bits (the last two
dotted quads) to identify host interfaces. Class B addresses always have
the leftmost 2 bits of the leftmost byte set to 1 0. This leaves 14 bits
left to specify the network address giving 32767 available B class
networks. B Class networks thus have a range of 128 to 191 for the first
of the dotted quads, with each network containing up to 32,766 possible
interfaces.
<item>Class C IP network numbers use the leftmost 24 bits (the leftmost
three bytes) to identify the network, leaving 8 bits (the rightmost
byte) to identify host interfaces. Class C addresses always start with
the leftmost 3 bits set to 1 1 0 or a range of 192 to 255 for the
leftmost dotted quad. There are thus 4,194,303 available C class network
numbers, each containing 254 interfaces. (C Class networks with the
first byte greater than 223 are however reserved and unavailable for use).
</itemize>
In summary:
<tscreen><verb>
Network class Usable range of first byte values (decimal)
A 1 to 126
B 128 to 191
C 192 to 254
</verb></tscreen>
<p>
There are also special addresses that are reserved for 'unconnected'
networks - that is networks that use IP but are not connected to the
Internet, These addresses are:-
<itemize>
<item>One A Class Network<newline>
10.0.0.0
<item>16 B Class Networks<newline>
172.16.0.0 - 172.31.0.0
<item>256 C Class Networks
192.168.0.0 - 192.168.255.0
</itemize>
<p>
You will note that this document uses these sequences throughout to avoid
confusion with 'real' networks and hosts.
<sect1>Network numbers, interface addresses and broadcast addresses
<p>
IP numbers can have three possible meanings:-
<itemize>
<item>the address of an IP network (a group of IP devices sharing common
access to a transmission medium - such as all being on the same Ethernet
segment). A network number will always have the interface (host) bits of
the address space set to 0 (unless the network is sub-networked - as we
shall see);
<item>the broadcast address of an IP network (the address used to 'talk',
simultaneously, to all devices in an IP network). Broadcast
addresses for a network always have the interface (host) bits of the the
address space set to 1 (unless the network is sub-networked - again, as
we shall see).
<item>the address of an interface (such as an Ethernet card or PPP interface
on a host, router, print server etc). These addresses can have any value
in the host bits <bf/except/ all zero or all 1 - because with the host bits all
0, the address is a network address and with the host bits all 1 the
address is the broadcast address.
</itemize>
<p>
In summary and to clarify things
<tscreen><verb>
For an A class network...
(one byte of network address space followed by three bytes of host
address space)
10.0.0.0 is an A Class network number because all the host
bits of the address space are 0
10.0.1.0 is a host address on this network
10.255.255.255 is the broadcast address of this network
because all the host bits of the address space are 1
For a B class network...
(two bytes of network address space followed by two bytes of host
address space)
172.17.0.0 is a B Class network number
172.17.0.1 is a host address on this network
172.17.255.255 is the network broadcast address
For a C Class network...
(three bytes of network address space followed by one byte of host
address space)
192.168.3.0 is a C Class network number
192.168.3.42 is a host address on this network
192.168.3.255 is the network broadcast address
</verb></tscreen>
<p>
Almost all IP network numbers remaining available for allocation at
present are C Class addresses.
<sect1>The network mask
<p>
The network mask is more properly called the subnetwork mask. However,
it is generally referred to as the network mask.
<p>
It is the network mask and its implications on how IP addresses are
interpreted <em/locally/ on an IP network segment that concerns us most
here, as this determines what (if any) sub-networking occurs.
<p>
The standard (sub-) network mask is all the network bits in an address
set to '1' and all the host bits set to '0'. This means that the
standard network masks for the three classes of networks are:-
<itemize>
<item>A Class network mask: 255.0.0.0
<item>B Class network mask: 255.255.0.0
<item>C Class network mask: 255.255.255.0
</itemize>
<p>
There are two important things to remember about the network mask:-
<itemize>
<item>The network mask affects only the <bf/local/ interpretation of
<bf/local/ IP numbers (where local means on this particular network segment);
<item>The network mask is <bf/not/ an IP number - it is used to modify
how local IP numbers are interpreted locally.
</itemize>
<sect>What are subnets?
<p>
A subnet is a way of taking a single IP network address and <bf/locally/
splitting it up so that this single network IP address can actually be
used on several interconnected local networks. Remember, a single IP
network number can only be used on a single network.
<p>
The important word here is <bf/locally/: as far as the world outside the
machines and physical networks covered by the sub-netted IP network are
concerned, nothing whatsoever has changed - it is still just a single IP
network. This is important - sub-networking is a <bf/local/ configuration
and is invisible to the rest of the world.
<sect>Why subnetwork?
<p>
The reasons behind sub-networking date back to the early specification of
IP - where just a few sites were running on Class A network numbers,
which allow for millions of connected hosts.
<p>
It is obviously a huge traffic and administration problem if all IP
computers at a large site need to be connected to the same network:
trying to manage such a huge beast would be a nightmare and the network
would (almost certainly) collapse under the load of its own traffic
(saturate).
<p>
Enter sub-networking: the A class IP network address can be split up to
allow its distribution across several (if not many) separate networks.
The management of each separate network can easily be delegated as well.
<p>
This allows small, manageable networks to be established - quite
possibly using different networking technologies. Remember, you cannot mix
Ethernet, Token Ring, FDDI, ATM etc on the same physical network - they
can be interconnected, however!
<p>
Other reasons for sub-networking are:-
<itemize>
<item>Physical site layout can create restrictions (cable run lengths)
in terms of the how the physical infrastructure can be connected,
requiring multiple networks. Sub-networking allows this to be done in an
IP environment using a single IP network number.
<newline><newline>
This is in fact now very commonly done by ISPs who wish to give their
permanently connected clients with local networks static IP numbers.
<item>Network traffic is sufficiently high to be causing significant
slow downs. By splitting the network up using subnetworks, traffic that
is local to a network segment can be kept local - reducing overall
traffic and speeding up network connectivity without requiring more
actual network bandwidth;
<item>Security requirements may well dictate that different classes of
users do not share the same network - as traffic on a network can always
be intercepted by a knowledgeable user. Sub-networking provides a way to
keep the marketing department from snooping on the R &amp; D network traffic
(or students from snooping on the administration network)!
<item>You have equipment which uses incompatible networking technologies
and need to interconnect them (as mentioned above).
</itemize>
<sect>How to subnetwork a IP network number
<p>
Having decided that you need to subnetwork your IP network number, how
do you go about it? The following is an overview of the steps which will
then be explained in detail:-
<itemize>
<item>Set up the physical connectivity (network wiring and network
interconnections - such as routers;
<item>Decide how big/small each subnetwork needs to be in terms of the
number of devices that will connect to it - ie how many usable IP
numbers are required for each individual segment.
<item>Calculate the appropriate network mask and network addresses;
<item>Give each interface on each network its own IP address and the
appropriate network mask;
<item>Set up the routes on the routers and the appropriate gateways,
routes and/or default routes on the networked devices;
<item>Test the system, fix problems and then relax!
</itemize>
<p>
For the purpose of this example, we will assume we are sub-networking a single C
class network number: 192.168.1.0
<p>
This provides for a maximum of 254 connected interfaces (hosts), plus
the obligatory network number (192.168.1.0) and broadcast address
(192.168.1.255).
<sect1>Setting up the physical connectivity
<p>
You will need to install the correct cabling infrastructure for all the
devices you wish to interconnect designed to meet your physical layout.
<p>
You will also need a mechanism to interconnect the various segments
together (routers, media converters etc.).
<p>
A detailed discussion of this is obviously impossible here. Should you
need help, there are network design/installation consultants around who
provide this sort of service. Free advice is also available on a number of
Usenet news groups (such as comp.os.linux.networking).
<sect1>Subnetwork sizing
<p>
There is a play off between the number of subnetworks you create and 'wasted'
IP numbers.
<p>
Every individual IP network has two addresses unusable as interface
(host) addresses - the network IP number itself and the broadcast
address. When you subnetwork, each subnetwork requires its own, unique
IP network number and broadcast address - and these have to be valid
addresses from within the range provided by the IP network that you are
sub-networking.
<p>
So, by sub-networking an IP network into two separate subnetworks, there
are now <bf/two/ network addresses and <bf/two/ broadcast addresses -
increasing the 'unusable' interface (host) addresses; creating 4
subnetworks creates <bf/eight/ unusable interface (host) addresses and
so on.
<p>
In fact the smallest usable subnetwork consists of 4 IP numbers:-
<itemize>
<item>Two usable IP interface numbers - one for the router interface on
that network and one for the single host on that network.
<item>One network number.
<item>One broadcast address.
</itemize>
<p>
Quite why one would want to create such a small network is another
question! With only a single host on the network, any network
communication must go out to another network. However, the example does
serve to show the law of diminishing returns that applies to
sub-networking.
<p>
In principle, you can only divide your IP network number into 2^n (where
n is one less that the number of host bits in your IP network number)
equally sized subnetworks (you can subnetwork a subnetwork and combine
subnetworks however).
<p>
So be realistic about designing your network design - you want the
<bf/minimum/ number of separate local networks that is consistent with
management, physical, equipment and security constraints!
<sect1>Calculating the subnetwork mask and network numbers
<p>
The network mask is what performs all the <bf/local/ magic of dividing
an IP network into subnetworks.
<p>
The network mask for an un-sub-networked IP network number is simply a
dotted quad which has all the 'network bits' of the network number
set to '1' and all the host bits set to '0'.
<p>
So, for the three classes of IP networks, the standard network masks
are:-
<itemize>
<item>Class A (8 network bits) : 255.0.0.0
<item>Class B (16 network bits): 255.255.0.0
<item>Class C (24 network bits): 255.255.255.0
</itemize>
<p>
The way sub-networking operates is to <em/borrow/ one or more of the
available host bits and make then make interfaces <bf/locally/ interpret
these borrowed bits as part of the network bits. So to divide a network
number into two subnetworks, we would borrow one host bit by setting the
appropriate bit in the network mask of the first (normal) host bit to '1'.
<p>
For a C Class address, this would result in a netmask of
<newline>
11111111.11111111.11111111.10000000
<newline>
or 255.255.255.128
<p>
For our C Class network number of 192.168.1.0, these are some of the
sub-networking options you have:-
<code>
No of No of
subnets Hosts/net netmask
2 126 255.255.255.128 (11111111.11111111.11111111.10000000)
4 62 255.255.255.192 (11111111.11111111.11111111.11000000)
8 30 255.255.255.224 (11111111.11111111.11111111.11100000)
16 14 255.255.255.240 (11111111.11111111.11111111.11110000)
32 6 255.255.255.248 (11111111.11111111.11111111.11111000)
64 2 255.255.255.252 (11111111.11111111.11111111.11111100)
</code>
<p>
In principle, there is absolutely no reason to follow the above way of
subnetworking where network mask bits are added from the most
significant host bit to the least significant host bit. However, if you
do not do it this way, the resulting IP numbers will be in a <em/very/
odd sequence! This makes it extremely difficult for us humans to decide
to which subnetwork an IP number belongs as we are not too good at thinking
in binary (computers on the other hand are and will use whatever scheme
you tell them with equal equanimity).
<p>
Having decided on the appropriate netmask, you then need to work out
what the various Network and broadcast addresses are - and the IP number
range for each of these networks. Again, considering only a C Class IP
Network number and listing only the <em/final/ (host part) we have:-
<code>
Netmask Subnets Network B'cast MinIP MaxIP Hosts Total Hosts
--------------------------------------------------------------------------
128 2 0 127 1 126 126
128 255 129 254 126 252
192 4 0 63 1 62 62
64 127 65 126 62
128 191 129 190 62
192 255 193 254 62 248
224 8 0 31 1 30 30
32 63 33 62 30
64 95 65 94 30
96 127 97 126 30
128 159 129 158 30
160 191 161 190 30
192 223 193 222 30
224 255 225 254 30 240
</code>
<p>
As can be seen, there is a very definite sequence to these numbers,
which make them fairly easy to check. The 'downside' of sub-networking is
also visible in terms of the reducing total number of available host
addresses as the number of subnetworks increases.
<p> With this information, you are now in a position to assign host and
network IP numbers and netmasks.
<sect>Routing
<p>
If you are using a Linux PC with two network interfaces to route between
two (or more) subnets, you need to have IP Forwarding enabled in your
kernel. Do a
<code>
cat /proc/ksyms | grep ip_forward
</code>
<p>
You should get back something like...
<code>
00141364 ip_forward_Rf71ac834
</code>
<p>
If you do not, then you do not have IP-Forwarding enabled in your kernel
and you need to recompile and install a new kernel.
<p>
For the sake of this example, let us assume that you have decided to
subnetwork you C class IP network number 192.168.1.0 into 4 subnets
(each of 62 usable interface/host IP numbers). However, two of these
subnets are being combined into a larger single network, giving three
physical networks.
<p>
These are :-
<code>
Network Broadcast Netmask Hosts
192.168.1.0 192.168.1.63 255.255.255.192 62
192.168.1.64 192.168.1.127 255.255.255.192 62
192.168.1.128 192.168.1.255 255.255.255.128 124 (see note)
</code>
<p>
Note: the reason the last network has only 124 usable network addresses
(not 126 as would be expected from the network mask) is that it is
really a 'super net' of two subnetworks. Hosts on the other two networks
will interpret 192.168.1.192 as the <em/network/ address of the 'non-existent'
subnetwork. Similarly, they will interpret 192.168.1.191
as the broadcast address of the 'non-existent' subnetwork.
<p>
So, if you use 192.168.1.191 or 192 as host addresses on the third
network, then machines on the two smaller networks will not be able to
communicate with them.
<p>
This illustrates an important point with subnetworks - the usable
addresses are determined by the <bf/SMALLEST/ subnetwork in that address
space.
<sect1>The routing tables
<p>
Let us assume that a computer running Linux is acting as a router for
this network. It will have three network interfaces to the local LANs
and possibly a fourth interface to the Internet (which would be its
default route.
<p>
Let us assume that the Linux computer uses the lowest available IP
address in each subnetwork on its interface to that network. It would
configure its network interfaces as
<code>
Interface IP Address Netmask
eth0 192.168.1.1 255.255.255.192
eth1 192.168.1.65 255.255.255.192
eth2 192.168.1.129 255.255.255.128
</code>
<p>
The routing it would establish would be
<code>
Destination Gateway Genmask Iface
192.168.1.0 0.0.0.0 255.255.255.192 eth0
192.168.1.64 0.0.0.0 255.255.255.192 eth1
192.168.1.128 0.0.0.0 255.255.255.128 eth2
</code>
<p>
On each of the subnetworks, the hosts would be configured with their own
IP number and net mask (appropriate for the particular network). Each host
would declare the Linux PC as its gateway/router, specifying the Linux
PCs IP address for its interface on to that particular network.
<p>
Robert Hart
Melbourne, Australia March 1997.
</article>

299
LDP/retired/ISP-Connectivity.sgml Normal file
View File

@ -0,0 +1,299 @@
<!doctype linuxdoc system>
<article>
<title>
ISP-Connectivity-mini-HOWTO
<author>Michael Strates, <tt>mstrates@croftj.net</tt>
<date>v2.0.1, 2001-11-28
<abstract>
This document describes how to setup PPP, connect up to your
ISP, configure mail and news, get a permanent IP (if available),
get a domain name, and have a bonda fide system running
in a little over thirty minutes.
<p>
<bf>Archived Document Notice:</bf> This document has been archived by the LDP
because it does not apply to modern Linux systems. It is no longer
being actively maintained.
</p>
</abstract>
<toc>
<p>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect> Introduction
<p>
The main goal of this document obviously is to make the new user
friendly with the many terms of connecting your Linux PC up to
the Internet, obtaining IP addresses, domain names, and setting things
up. This guide is intended for the intermediate user in mind, although
intelligent newbies shouldn't have any problems.
<p>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect1> New versions of this document
<p>
New versions of this document will be periodically posted to
<it>comp.os.linux.answers</it>. They will also be added to the
various anonymous FTP sites who archive such information,
including:
<p>
<tt>
<htmlurl url="ftp://sunsite.unc.edu/pub/Linux/docs/HOWTO"
name="ftp://sunsite.unc.edu/pub/Linux/docs/HOWTO">
</tt>
<p>
In addition, you should generally be able to find this document
on the Linux Documentation Project page via:
<p>
<tt>
<htmlurl url="http://sunsite.unc.edu/LDP/"
name="http://sunsite.unc.edu/LDP/">
</tt>
<p>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect1> Feedback
<p>
I certaintly welcome any feedback about this HOWTO, spelling mistakes,
how it all worked out, thankyou notes and critisisms. I hope I helped
a few people with this HOWTO, and if I did, I'd be really happy to
hear from you.
<p>
<tt>
<htmlurl url="mailto:mstrates@croftj.net"
name="mstrates@croftj.net">
</tt>
<p>
<tt>
<htmlurl url="http://linloft.home.ml.org/"
name="http://linloft.home.ml.org/">
</tt>
<p>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect1> Standard Disclaimer
<p>
No liability for the contents of this documents can be accepted.
Use the concepts, examples and other content at your own risk.
As this is a new edition of this document, there may be errors
and inaccuracies, that may of course be damaging to your system.
Proceed with caution, and although this is highly unlikely,
I don't take any responsibility for that.
<p>
Naturally, there are probably better and easier ways to do things
in this document. There will always be another way in the Linux
World. This is the way I've done things, and that's the way I'll
be presenting them in this HOWTO.
<p>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect1> Copyright Information
<p>
This document is copyrighted (c)1997 Michael Strates and
distributed under the terms of the GNU Free Documentation License,
which can be obtained from
<a href="http://www.fsf.org/licenses/fdl.html">http://www.fsf.org/licenses/fdl.html</a>.
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect> Connecting to the Outside World
<p>
In this document, we'll explain how to do this using PPP (Point
to Point Protocol), a popular protocol nearly always used over the
Internet. It allows your modem to <tt>speak</tt> to the outside
world. This is what applications like Trumpet Winsock in Windows
3.x did, and many other programs that you've probably have never
seen.
<p>
In Linux, we use a thing called chat to do the dialing up to the
ISP and then use a utility called pppd to 'use' the connection. In
a sense, chat is your dialer, and pppd is your protocol. We'll
describe how to setup both below.
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect1> Talking and Communicating with pppd and chat
<p>
Probably the easiest way to go about things is to make a shell
script in root's home directory called <tt>ppp-connect</tt> and
involke the script whenever you wish to make your connection. We'll
discuss this method.
<p>
Open up your favourite editor as root on ~/ppp-connect. You'll
then have to decide on your parameters.
<p>
<it>pppd connect 'chat -v "" "your_init_string" "" ATDTisp_number
CONNECT "" ogin: your_username word: your_passwd' /dev/tty(0/1/2) speed
modem</it>
<p>
pppd involkes /usr/sbin/pppd on my system, then loads up chat to do the
dialing. Chat sends <it>your_init_string</it> to the modem, then
dials <it>isp_number</it>. It then waits for CONNECT, then waits for
ogin: (l removed as the first character is sometimes lost), sends
<it>your_passwd</it>, chat then terminates and hands the show over to
pppd.
<p>
The last of the command specifies your modem port (mine's /dev/ttyS1). In
most cases it will be ttyS1 (COM2: in DOS), ttyS0 (COM1: in DOS), or if
your using Slackware, cua1 or cua0. The speed is the speed of the modem. I
use 115200 for my modem (a 33.6k). If you have got a fairly recent
computer (one with a 16550 UART), then I wouldn't go any lower than 57600.
Otherwise, for 14.4k 38400. Modem just tells pppd that it's a serial/modem
based connection. Remove the -v option if you don't want verbose logging
to your logfiles.
<p>
The scenario below is one of a person who dials up an ISP that
automatically starts PPP for them, ie; they don't have a shell that
actually starts. This is his command in his ~/ppp-connect:
<p>
<it>pppd connect 'chat "" "ATZ" "" ATDT555-1800
CONNECT "" ogin: johnny word: blackjak' /dev/ttyS1 115200
modem</it>
<p>
But for some people, they're ISP starts up a shell and doesn't
automatically start PPP this may be a problem. Luckily, chat can deal with
that too. You just add another command to your chat script. For example,
below this johnny character is using an ISP that just dumps him to a
shell, requiring him to type ppp to get a ppp connection. His shell prompt
ends with a $.
<it>pppd connect 'chat "" "ATZ" "" ATDT555-1800
CONNECT "" ogin: johnny word: blackjak $ ppp' /dev/ttyS1 115200
modem</it>
<p>
If it's more than one word, ensure you quote it. I hope you can see the
drift of this, and are able to create your own script up to suit your
connection. Simply modify either the first johnny or the second johnny
script to suit your taste, port, server, etc and save the file.
<p>
Now you've made your file, ensure that only root can execute, read or
write to it. This is extreemly important. Also make sure nobody can
read your logfiles, if you decide to leave the -v option in, as your
password is seen in cleartext in the logs (I don't see much need for -v,
if you don't know what I'm talking about, leave -v out).
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect1> IP's, Domain Names and Subnets
<p>
For most people using the options above, a changing IP address won't
bother them. These people include basic, easy going users, that just have
dialup accounts, and aren't very technically minded. For those people,
skim read this section, I'll come to important things you need to do to
setup your system properly. Newbies, skip the sections dealing with
permanent IP, Domain Names, Subnets, and just read the last bit of this
section.<p>
Getting a permanent IP address might be free for your ISP, so if in doubt
ask them. Personally, I'd pay for a permanent IP address. It lets you send
e-mail to and from using a unique IP or domain, etc. If you want to get
yourself a permanent IP, write an e-mail to root@yourisp.com, and ask him
nicely if he can arrange a permanent IP for you.
<p>
When you get your permanent IP address, grep through your /etc directory
to find where your old IP addresses are. I had to change files in my
sendmail directory and /etc/hosts. There are some other key files that you
will only discover with grepping. Open up /etc/hosts, and add your new IP
address in the standard format. Reboot your computer, and you should be
ready to go.
<p>
You'll now need to change your chat script to reflect your new settings.
If you are forced into PPP as soon as you start your connection, you'll
need to tell your System Administrator of your ISP to ensure their PPP
system recognises that you have a permanent IP address and allocates you
that instead of a changing one. If you get dumped at a shell prompt, and
you need to type ppp or something to start the connection, instead of
typing that, change your ~/ppp-connect script to send this instead of just
ppp or whatever when it sees $ or whatever your shell prompt is.
<p>
<it>/usr/sbin/pppd :Your_IP_Address</it>
<p>
Substitute your IP address for the IP address your ISP gave to you. Be
sure you encapsulate the thing in " " marks when you put it into your chat
script. If this doesn't work, consult your ISP where your PPP daemon is
located, and ask him for the command to give. You could just try leaving
it as is and seeing if the server will recognise you and give you your
rightful address.
<p>
The next thing probably to do is to get yourself a domain name. I know
that in Australia, .asn.au and .org.au are free. In the United States, you
can get a .us domain for free, but they tend to be long. If your in
Australia, you must go to
<htmlurl url="http://www.aunic.net/" name="http://www.aunic.net/">
to register your domains. In the United States, it is
<htmlurl url="http://www.internic.net/" name="http://www.internic.net/"> .
<p>
To register domains you need to be able to provide DNS services, and gorey
stuff like that. If your ISP can't provide these, throw out an official
.asn.au or whatever domain out the window, and get a Monolith Internet
Domain.
<p>
Monolith offer free domains to anybody and anyone all around the world.
Everything is done without human interaction, via a web forms interface
with your browser. Your domain comes in the form of Your_Choice.ml.org.
Monolith will then host the DNS locally for you. If you want to send and
receive mail from that domain, ask your ISP to become a mail exchanger for
you.
<p>
Go to
<htmlurl url="http://www.ml.org/" name="http://www.ml.org/">
and fill out an application, enter the NIC with your username and
password, and make a FREED domain. You'll need to enter your IP address,
so have that ready. Your domain will be in the DNS in a couple of days.
<p>
Okay now, we'll move onto the newbies section, or for those people who
can't get a permanent IP address or a domain name. All you have to do is
edit /etc/hosts as root, call your site something that won't clash, give
it a 10.10.10 or something for an IP address and reboot your computer.
<p>
There you go, you've just setup your computer with pppd and chat in just
ten minutes. Now let's move onto the next section, which deals with
Electronic Mail.
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect> Electronic Mail on your Linux Box
<p>
One of the most important aspects of the Internet, is it's fasinating
capaiblity to transfer mail to and from countries, or more locally
perhaps. Linux is extreemly strong in easy mail packages for the console.
The one we're going to document today is called Pine (Program for Internet
Mail and News), made by the University of Washington, and to download the
mail, a program called Fetchmail, made by Eric S. Raymond. Both should be
included in your Linux distribution.
<p>
Fetchmail is a program that downloads your e-mail from your server using
POP, transfers the mail onto your computer and then deletes it off the
server, much like programs like Eudora or Microsoft Internet Mail/Exchange
do. To configure and automate fetchmail, you use a file in your home
directory called .fetchmailrc. Simply open up ~/.fetchmailrc
(Remember: your doing this bit as yourself, not as root) with your
favourite editor and observe the command lin eoptions below:
<p>
<EM>poll mail.yourisp.com proto pop3 user login_name password your_passwd</EM>
<p>
<EM>user login_name with pass your_passwd is login_name here</EM>
<p>
All you have to do is replace <EM>mail.yourisp.com</EM> with the name of
the mail server of your ISP, <EM>your_passwd</EM> with your password, and
<EM>login_name</EM> with your login name.
<p>
An important thing to note. For Pine and this procedure to work correctly,
your login name must corrospond with the login name you use on your ISP.
That is your local login name must match the one you use on your server,
and your e-mail address.
<p>
Next, ensure that .fetchmailrc has the correct permissions (user
read/write only) and your laughing. Fetchmail can be started in two ways,
in standard mode (where it'll fetch messages from the server and
terminate), or in daemon mode (where it will stay active, and
check/download mail every X seconds). To use daemon mode, type
<it>fetchmail -a -d(Seconds between Polls)</it>. -a ensures it downloads
all mail. To use the standard mode, just type <it>fetchmail -a</it>.
<p>
Next, you need to setup Pine. Open up Pine, by typing pine at your prompt,
choose Setup - Configuration. Setup your userdomain as the domain in your
e-mail address, for example jack@linux.org, would be linux.org. Next,
setup smtp-server as your POP mail server (the same you used in the
fetchmail setup). So we enter www.linux.org. If you want news, setup your
nntp server to your ISP's news server.
<p>
So there you have it folks, everything should be working now. To connect
up to your ISP, just run ~/ppp-connect as root. Then, to get your e-mail
run fetchmail -a as yourself. To browse your e-mail and news, use
Pine. Install a text-based browser such as Lynx to browse the web if you
like.
<p>
<it>Send any comments questions and suggestions to
mstrates@croftj.net</it>
<p>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
</article>

1184
LDP/retired/KickStart-HOWTO.sgml Normal file
View File

File diff suppressed because it is too large Load Diff

3721
LDP/retired/Laptop-HOWTO.sgml Normal file
View File

File diff suppressed because it is too large Load Diff

400
LDP/retired/Loopback-Encrypted-Filesystem-HOWTO.sgml Normal file
View File

@ -0,0 +1,400 @@
<!doctype linuxdoc system>
<!-- Loopback Encrypted Filesystem HOWTO by Ryan T. Rhea -->
<article>
<!-- Title information -->
<title>Loopback Encrypted Filesystem HOWTO
<author>Copyright by Ryan T. Rhea,
<tt/rhear@cs.winthrop.edu/
<date>v1.1, 29 November 1999
<abstract>
This document explains how to setup and then use a filesystem
that, when mounted by a user, dynamically and transparently
encrypts its contents. The filesystem is stored in a regular
file, which can be hidden or named non-conspicuously such that it
would most likely be overlooked. This allows for a high level of
secure storage of data.
<p>
<bf>Archived Document Notice:</bf> This document has been archived by the LDP
because it does not apply to modern Linux systems. It is no longer
being actively maintained.
</p>
</abstract>
<!-- Table of contents -->
<toc>
<!-- Begin the document -->
<sect>Before you begin
<p>
This process requires the kernel source code, knowledge of
compiling this
code, and a lot of patience. I highly recommend having a boot
disk ready.
Also, be sure to have a backup before you permanently store your
important
data on the encrypted filesystem - it can be corrupted like any
other
filesystem.
As a minimum, you will have to patch to at least version 2.2.9 of
the linux
kernel before continuing. There are further instructions on
applying patches
in the <ref id="Details"> section later in this document.
Kernel source can be found at:
<tscreen>
<url url="ftp://ftp.kerneli.org/">
</tscreen>
There is a HOWTO on the process of recompiling kernels at:
<tscreen>
<url url="http://metalab.unc.edu/LDP/HOWTO/">
</tscreen>
This document may be reproduced and distributed in whole or in
part, without fee, subject to the following conditions:
<itemize>
<item>The copyright notice and this permission notice must be
preserved complete on all complete or partial copies.
<item>Any translation or derived work must be approved by the
author
in writing before distribution.
<item>If you distribute this work in part, instructions for
obtaining
he complete version of this manual must be included, and a means
for obtaining a complete version provided.
<item>All source code in this document is placed under the GNU
General Public License, available via anonymous FTP from:
</itemize>
<tscreen>
<url url="ftp://prep.ai.mit.edu/pub/gnu/COPYING/">
</tscreen>
<sect>Introduction
<p>
The process uses the device '/dev/loop*' (where * can be 0-7 on
most installations) to mount a loopback filesystem. The same
process can be used without encryption to store a linux
filesystem on a non-linux partition. There is a HOWTO on this at
the LDP site mentioned previously.
Different types of encryption can be used, including XOR, DES,
twofish, blowfish, cast128, serpent, MARS, RC6, DFC, and IDEA.
The program 'losetup' (loopback setup) is what associates your
encrypted file with a filesystem and it's cipher type. According
to Alexander
Kjeldaas, who maintains kerneli.org and the international crypto
patches, DES
and losetup are currently incompatible. This is due to
differences in the way
the two handle parity bits. There are no plans to support DES as
it is much
more insecure than the other ciphers.
Twofish, blowfish, cast128, and serpent are all licensed free for
any use.
The others may or may not have licensing restrictions. Several
of them are
candidates for the AES standard. The finalists will provide
royalty free use
of their ciphers worldwide.
This document uses the serpent algorithm because it is strong yet
remarkably fast, and it's freely distributable under the GPL.
According to
it's documentation, serpent uses a 128-bit block cipher designed
by Ross
Anderson, Eli Biham and Lars Knudsen. It provides users with the
highest
practical level of assurance that no shortcut attacks will be
found. The
documentation on serpent as well as the source code can be found
at:
<tscreen>
<url url="http://www.cl.cam.ac.uk/~rja14/serpent.html">
</tscreen>
Also, this document assumes that the ciphers are compiled
directly into the
kernel. You may install them as modules, but the technique is
not discussed
in this document. You will have to edit the file
'/etc/conf.module'; the
process is discussed in detail in the kernel compilation HOWTO
referenced previously.
<sect>Summary
<p>
There are many steps involved in the process. I will provide
<ref id="Details"> for these steps in the next section. I thought
it would
be nice to provide a summary first to provide reference (if you
are experienced with unix/linux you probably don't need the
details anyway). Here they are summarized as follows:
<enum>
<item>Download the newest international crypto patch (I used
'patch-int-2.2.10.4' at the time this document was written) from:
<p><tscreen>
<url url="http://ftp.kerneli.org/pub/kerneli/">
</tscreen>
<p><item>Patch the kernel
<p><item>Run 'config' (or 'menuconfig' or 'xconfig') to configure
your
'MakeFile' for the new kernel. The options to enable encryption
are
scattered. First of all, before you will see any other options
you must
enable 'Prompt for development and/or incomplete code/drivers'
under 'Code
Maturity level options'. Under 'Crypto options' enable 'crypto
ciphers' and
'serpent'. Once again, this document assumes you are using
serpent, but try
whatever you want. Remember that DES is known to be incompatible
as of
2.2.10.4 - it may never be supported at all. There are several
important options to select under 'Block Devices'. These include
'Loopback
device support', 'Use relative block numbers as basis for
transfer functions
(RECOMMENDED)', and 'General encryption support'. DO NOT select
'cast 128' or
'twofish' encryption here. Also note that you don't need any of
the crypto
options under the various network categories. I will not go any
further into
configuration of the kernel, it is out of the scope of this
document and can
be found at the LDP site.
<p><item>Compile the new kernel.
<p><item>Edit '/etc/lilo.conf' to add the new kernel image. Run
'lilo -v' to
add the kernel to the boot loader.
<p><item>Download the source for the newest 'util-linux' (I used
'util-linux-2.9v') package from:
<p><tscreen>
<url url="ftp://ftp.kernel.org/pub/linux/utils/util-linux/">
</tscreen>
<p><item>Extract the 'util-linux' source.
<p><item>Apply the corresponding patch found in your
'/usr/src/linux/Documentation/crypto/' directory.
<p><item>CAREFULLY read the 'INSTALL' file! This package
contains the
sources for many system dependent files (important tools such as
'login', 'passwd', and 'init'). If you don't carefully edit the
MCONFIG
file before compiling these sources have a boot disk and/or
shotgun ready
because your system will be quite confused. Basically you want
to set almost
all of the 'HAVE_*' fields equal to yes so that the important
authentication
tools are not compiled and written over. The tools you do want
rebuilt
are 'mount' and 'losetup' to accommodate the new encryption
schemes. I
suggest that you refer to the <ref id="Details"> section below
for this step.
<p><item>Compile and install the 'util-linux' source
<p><item>Reboot the machine with the new kernel.
<p><item>Edit '/etc/fstab', adding an entry for your mount point
as follows:
<p><tscreen><code>
/dev/loop0 /mnt/crypt ext2 user,noauto,rw,loop 0 0
</code></tscreen>
<p><item>Create the directory that will hold your filesystem, as
in
'/mnt/crypt' above.
<p><item>As the user, create your encrypted file as follows:
<p><tscreen><verb>
dd if=/dev/urandom of=/etc/cryptfile bs=1M count=10
</verb></tscreen>
<p><item>Run losetup as follows:
<p><tscreen><verb>
losetup -e serpent /dev/loop0 /etc/cryptfile
</verb></tscreen>
You only have one chance to enter the password, be careful. If
you want to
double-check your password, you can use the command:
<p><tscreen><verb>
losetup -d /dev/loop0
</verb></tscreen>
This will deactivate your loop device. Next you will run losetup
again to
test your password, as follows:
<p><tscreen><verb>
losetup -e serpent /dev/loop0 /etc/cryptfile
</verb></tscreen>
<p><item>Make your ext2 filesystem as follows:
<p><tscreen><verb>
mkfs -t ext2 /dev/loop0
</verb></tscreen>
<p><item>Now you can mount the encrypted filesystem with:
<p><tscreen><verb>
mount -t ext2 /dev/loop0 /mnt/crypt
</verb></tscreen>
<p><item>When your done, you want to unmount and protect your
filesystem as
follows:
<p><tscreen><verb>
umount /dev/loop0
losetup -d /dev/loop0
</verb></tscreen>
</enum>
<sect>Details<label id="Details">
<p><bf/Kernel Patches:/
You can upgrade from '2.2.x' releases by patching. Each patch
that is released for '2.2.x' contains bugfixes. New features
will be added to the Linux '2.3.x' development kernel. To
install by patching, get all the newer patch files and do the
following:
<tscreen><verb>
cd /usr/src
gzip -cd patchXX.gz | patch -p0
</verb></tscreen>
Repeat xx for all versions bigger than the version of your
current source tree, IN ORDER.
The default directory for the kernel source is '/usr/src/linux'.
If your source is installed somewhere else, I would suggest using
a symbolic link from '/usr/src/linux'.
<p><bf/Editing 'MCONFIG' for the 'util-linux' package
compilation:/
The following are excerpts from the 'MCONFIG' file I used to
compile the 'util-linux' package. Note that this is fairly
specific for my setup, which is loosely based on RedHat 5.2. The
point is to make sure you don't overwrite any important system
tools such as 'login', 'getty', or 'passwd'. Anyway, here are
the
important lines as follows:
<tscreen><code>
CPU=$(shell uname -m | sed s/I.86/intel/)
LOCALEDIR=/usr/share/locale
HAVE_PAM=no
HAVE_SHADOW=yes
HAVE_PASSWD=yes
REQUIRE_PASSWORD=yes
ONLY_LISTED_SHELLS=yes
HAVE_SYSVINIT=yes
HAVE_SYSVINIT_UTILS=yes
HAVE_GETTY=yes
USE_TTY_GROUP=yes
HAVE_RESET=yes
HAVE_SLN=yes
CC=gcc
</code></tscreen>
<p><bf/Suggestions:/
Note that you could use any of the eight loopback devices, from
'dev/loop0'
to '/dev/loop7'. Use an inconspicuous directory for the mount
point. I would
suggest creating a folder with 700 permissions inside your home
folder. The
same goes for the file that holds the data. I use a filename
like 'sysfile'
or 'config.data' inside the '/etc' folder. This will usually get
overlooked.
I created very simple Perl scripts to mount and unmount the
filesystem with one command. Write these, make them executable
(chmod u+x), and store them somewhere in your path.
<tscreen><code>
#!/usr/bin/perl -w
#
#minimal utility to setup loopback encryption filesystem
#Copyright 1999 by Ryan T. Rhea
`losetup -e serpent /dev/loop0 /etc/cryptfile`;
`mount /mnt/crypt`;
</code></tscreen>
Name the above script 'loop', and then you can be on your way
with one command ('loop') and a password.
<tscreen><code>
#!/usr/bin/perl -w
#
#minimal utility to deactivate loopback encryption filesystem
#Copyright 1999 by Ryan T. Rhea
`umount /mount/crypt`;
`losetup -d /dev/loop0`;
</code></tscreen>
Name the second one 'unloop', and then typing 'unloop' will
quickly deactivate your filesystem.
</article>

743
LDP/retired/Loopback-Root-FS.sgml Normal file
View File

@ -0,0 +1,743 @@
<!DOCTYPE LINUXDOC SYSTEM>
<article>
<title>The Loopback Root Filesystem HOWTO
<author>by Andrew M. Bishop, <tt><htmlurl url="mailto:amb@gedanken.demon.co.uk" name="amb@gedanken.demon.co.uk"></tt>
<date>v1.1, 24 September 1999
<abstract>
This HOWTO explains how to use the Linux loopback device to create a Linux
native filesystem format installation that can be run from a DOS partition
without re-partitioning. Other uses of this same technique are also discussed.
</abstract>
<toc>
<sect>Introduction
<p>
<sect1>Copyright
<p>
The Loopback Root Filesystem HOWTO
Copyright (C) 1998,99 Andrew M. Bishop (amb@gedanken.demon.co.uk).
This documentation is free documentation; 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 program 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.
The GNU General Public License is available from <htmlurl url="http://www.fsf.org/" name="http://www.fsf.org/">
or, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
<sect1>Revision History
<p>
<descrip>
<tag>Version 1.0.0</tag>Initial Version (June 1998)
<tag>Version 1.0.1-1.0.3</tag>Slight Modifications, kernel version changes, typos etc. (1998 - July 1999)
<tag>Version 1.1</tag>Added Copyright Information and Re-Submitted (September 1999)
</descrip>
<sect>Principles of Loopback Devices and Ramdisks
<p>
First I will describe some of the general principles that are used in the
setting up of a loopback filesystem as the root device.
<sect1>Loopback Devices
<p>
A <bf>loopback device</bf> in Linux is a virtual device that can be used like any
other media device.
<p>
Examples of normal media devices are hard disk partitions like
<tt>/dev/hda1</tt>, <tt>/dev/hda2</tt>, <tt>/dev/sda1</tt>, or entire disks like
the floppy disk <tt>/dev/fd0</tt> etc. They are all devices that can be used to
hold a files and directory structures. They can be formatted with the
filesystem that is required (ext2fs, msdos, ntfs etc.) and then mounted.
<p>
The loopback filesystem associates a file on another filesystem as a complete
device. This can then be formatted and mounted just like any of the other
devices listed above. To do this the device called <tt>/dev/loop0</tt> or
<tt>/dev/loop1</tt> etc is associated with the file and then this new virtual
device is mounted.
<sect1>Ramdisk Devices
<p>
In Linux it is also possible to have another type of virtual device mounted as a
filesystem, this is the <bf>ramdisk device</bf>.
<p>
In this case the device does not refer to any physical hardware, but to a
portion of memory that is set aside for the purpose. The memory that is
allocated is never swapped out to disk, but remains in the disk cache.
<p>
A ramdisk can be created at any time by writing to the ramdisk device
<tt>/dev/ram0</tt> or <tt>/dev/ram1</tt> etc. This can then be formatted and
mounted in the same way that the loopback device is.
<p>
When a ramdisk is used to boot from (as is often done on Linux installation
disks or rescue disks) then the disk image (the entire contents of the disk as a
single file) can be stored on the boot floppy in a compressed form. This is
automatically recognised by the kernel when it boots and is uncompressed into
the ramdisk before it is mounted.
<sect1>The Initial Ramdisk Device
<p>
The <bf>initial ramdisk</bf> device in Linux is another important mechanism that
we need to be able to use a loopback device as a the root filesystem.
<p>
When the initial ramdisk is used the filesystem image is copied into memory and
mounted so that the files on it can be accessed. A program on this ramdisk
(called <tt>/linuxrc</tt>) is run and when it is finished a different device is
mounted as the root filesystem. The old ramdisk is still present though and is
mounted on the directory <tt>/initrd</tt> if present or available through the
device <tt>/dev/initrd</tt>.
<p>
This is unusual behaviour since the normal boot sequence boots from the
designated root partition and keeps on running. With the initial ramdisk option
the root partition is allowed to change before the main boot sequence is
started.
<sect1>The Root Filesystem
<p>
The root filesystem is the device that is mounted first so that it appears as
the directory called <tt>/</tt> after booting.
<p>
There are a number of complications about the root filesystem that are due to
the fact that it contains all files. When booting the <tt>rc</tt> scripts are
run, these are either the files in <tt>/etc/rc.d</tt> or <tt>/etc/rc?.d</tt>
depending on the version of the <tt>/etc/init</tt> program.
<p>
When the system has booted it is not possible to unmount the root partition or
change it since all programs will be using it to some extent. This is why the
initial ramdisk is so useful because it can be used so that the final root
partition is not the same as the one that is loaded at boot time.
<sect1>The Linux Boot Sequence
<p>
To show how the initial ramdisk operates in the boot sequence, the order of
events is listed below.
<p>
<enum>
<item>The kernel is loaded into memory, this is performed by <tt>LILO</tt> or
<tt>LOADLIN</tt>. You can see the <tt>Loading...</tt> message as this happens.
<item>The ramdisk image is loaded into memory, again this is performed by
<tt>LILO</tt> or <tt>LOADLIN.</tt> You can see the <tt>Loading...</tt> message
again as this happens.
<item>The kernel is initialised, including parsing the command line options and
setting of the ramdisk as the root device.
<item>The program <tt>/linuxrc</tt> is run on the initial ramdisk.
<item>The root device is changed to that specified in the kernel parameter.
<item>The init program <tt>/etc/init</tt> is run which will perform the user
configurable boot sequence.
</enum>
This is just a simplified version of what happens, but is sufficient to explain
how the kernel starts up and where the initial ramdisk is used.
<sect>How To Create a Loopback Root Device
<p>
Now that the general principles are explained the method of creating the
loopback device can be explained.
<sect1>Requirements
<p>
To create the loopback root device will require a number of things.
<p>
<itemize>
<item>A working Linux system.
<item>A way to copy large files onto the target DOS partition.
</itemize>
Most important is access to an installed Linux system. This is because the loop
device can only be created under Linux. This will mean that it is not possible
to bootstrap a working system from nothing. The requirements of the Linux
system that you use is that you can compile a kernel on it.
<p>
Once the loopback device is created it will be a large file. I have used an 80
MB files, but while this was sufficient for an X terminal it may not be enough
if you want to use it for much else. This file must be copied onto the DOS
partition, so either a network or a lot of floppy disks must be used.
<p>
The software that you will require includes
<itemize>
<item><tt>LOADLIN</tt> version 1.6 or above
<item>A version of <tt>mount</tt> that supports loopback devices
<item>A version of the kernel that supports the required options.
</itemize>
All of these should be standard for recent Linux installations.
<sect1>Creating the Linux Kernel
<p>
I created the loopback device using Linux kernel version 2.0.31, other versions
should also work, but they must have at least the options listed below.
<p>
The kernel options that you will need to enable are the following:
<itemize>
<item>RAM disk support (<tt>CONFIG_BLK_DEV_RAM</tt>).
<item>Initial RAM disk (initrd) support (<tt>CONFIG_BLK_DEV_INITRD</tt>).
<item>Loop device support (<tt>CONFIG_BLK_DEV_LOOP</tt>).
<item>fat fs support (<tt>CONFIG_FAT_FS</tt>).
<item>msdos fs support (<tt>CONFIG_MSDOS_FS</tt>).
</itemize>
The first two are for the RAM disk device itself and the initial ram disk
device. The next one is the loop back filesystem option. The last two are the
msdos filesystem support which is required to mount the DOS partitition.
<p>
Compiling a kernel without modules is the easiest option, although if you do
want modules then it should be possible although I have not tried it. If
modules are used then you should make sure that you have the options above
compiled in and not as modules themselves.
<p>
Depending on the kernel version that you have you may need to apply a kernel
patch. It is a very simple one that allows the loopback device to be used as
the root filesystem.
<itemize>
<item>Kernel versions before 2.0.0; I have no information about these.
<item>Kernel version 2.0.0 to 2.0.34; you need to apply the kernel patch for
2.0.x kernels as shown below.
<item>Kernel version 2.0.35 to 2.0.x; no kernel patch is required.
<item>Kernel version 2.1.x; you need to apply the kernel patch for 2.0.x or
2.2.x kernels as shown below, depending on the exact 2.1.x version.
<item>Kernel version 2.2.0 to 2.2.10; you need to apply the kernel patch for
2.2.x kernels as shown below.
<item>Kernel version 2.3.x; you need to apply the kernel patch for 2.2.x kernels
as shown below.
</itemize>
<p>
For 2.0.x kernels the file <tt>/init/main.c</tt> needs to have a single line
added to it as shown by the modified version below. The line that says
<tt>"loop", 0x0700</tt> is the one that was added.
<p>
<tscreen><verb>
static void parse_root_dev(char * line)
{
int base = 0;
static struct dev_name_struct {
const char *name;
const int num;
} devices[] = {
{ "nfs", 0x00ff },
{ "loop", 0x0700 },
{ "hda", 0x0300 },
...
{ "sonycd", 0x1800 },
{ NULL, 0 }
};
...
}
</verb></tscreen>
<p>
For 2.2.x kernels the file <tt>/init/main.c</tt> needs to have three lines added
to it as shown by the modified version below. The line that says <tt>"loop",
0x0700</tt> and the ones either side of it are the ones that were added.
<p>
<tscreen><verb>
static struct dev_name_struct {
const char *name;
const int num;
} root_dev_names[] __initdata = {
#ifdef CONFIG_ROOT_NFS
{ "nfs", 0x00ff },
#endif
#ifdef CONFIG_BLK_DEV_LOOP
{ "loop", 0x0700 },
#endif
#ifdef CONFIG_BLK_DEV_IDE
{ "hda", 0x0300 },
...
{ "ddv", DDV_MAJOR << 8},
#endif
{ NULL, 0 }
};
</verb></tscreen>
Once the kernel is configured it should be compiled to produce a <tt>zImage</tt>
file (<tt>make zImage</tt>). This file will be <tt>arch/i386/boot/zImage</tt>
when compiled.
<sect1>Creating the Initial Ramdisk Device
<p>
The initial ramdisk is most easily created as a loopback device from the start.
You will need to do this as root, the commands that you need to execute are
listed below, they are assumed to be run from root's home directory
(<tt>/root</tt>).
<p>
<tscreen><verb>
mkdir /root/initrd
dd if=/dev/zero of=initrd.img bs=1k count=1024
mke2fs -i 1024 -b 1024 -m 5 -F -v initrd.img
mount initrd.img /root/initrd -t ext2 -o loop
cd initrd
[create the files]
cd ..
umount /root/initrd
gzip -c -9 initrd.img &gt; initrdgz.img
</verb></tscreen>
There are a number of steps to this, but they can be described as follows.
<enum>
<item>Create a mount point for the initial ramdisk (an empty directory).
<item>Create an empty file of the size required. Here I have used 1024kB, you may
need less or more depending on the contents, (the size is the last parameter).
<item>Make an ext2 filesystem on the empty file.
<item>Mount the file onto the mount point, this uses the loopback device.
<item>Change to the mounted loopback device.
<item>Create the files that are required (see below for details).
<item>Move out of the mounted loopback device.
<item>Unmount the device.
<item>Create a compressed version for use later.
</enum>
<bf>Contents Of The Initial Ramdisk</bf>
The files that you will need on the ramdisk are the minimum requirements to be
able to execute any commands.
<itemize>
<item><tt>/linuxrc</tt> The script that is run to mount the msdos file system
(see below).
<item><tt>/lib/*</tt> The dynamic linker and the libraries that the programs
need.
<item><tt>/etc/*</tt> The cache used by the dynamic linker (not strictly needed,
but does stop it complaining).
<item><tt>/bin/*</tt> A shell interpreter (<tt>ash</tt> because it is smaller
than <tt>bash</tt>. The <tt>mount</tt> and <tt>losetup</tt> programs for
handling the DOS disk and setting up the loopback devices.
<item><tt>/dev/*</tt> The devices that will be used. You need
<tt>/dev/zero</tt> for <tt>ld-linux.so</tt>, <tt>/dev/hda*</tt> to mount the
msdos disk and <tt>/dev/loop*</tt> for the lopback device.
<item><tt>/mnt</tt> An empty directory to mount the msdos disk on.
</itemize>
The initial ramdisk that I used is listed below, the contents come to about
800kB when the overhead of the filesystem are taken into account.
<p>
<tscreen><verb>
total 18
drwxr-xr-x 2 root root 1024 Jun 2 13:57 bin
drwxr-xr-x 2 root root 1024 Jun 2 13:47 dev
drwxr-xr-x 2 root root 1024 May 20 07:43 etc
drwxr-xr-x 2 root root 1024 May 27 07:57 lib
-rwxr-xr-x 1 root root 964 Jun 3 08:47 linuxrc
drwxr-xr-x 2 root root 12288 May 27 08:08 lost+found
drwxr-xr-x 2 root root 1024 Jun 2 14:16 mnt
./bin:
total 168
-rwxr-xr-x 1 root root 60880 May 27 07:56 ash
-rwxr-xr-x 1 root root 5484 May 27 07:56 losetup
-rwsr-xr-x 1 root root 28216 May 27 07:56 mount
lrwxrwxrwx 1 root root 3 May 27 08:08 sh -&gt; ash
./dev:
total 0
brw-r--r-- 1 root root 3, 0 May 20 07:43 hda
brw-r--r-- 1 root root 3, 1 May 20 07:43 hda1
brw-r--r-- 1 root root 3, 2 Jun 2 13:46 hda2
brw-r--r-- 1 root root 3, 3 Jun 2 13:46 hda3
brw-r--r-- 1 root root 7, 0 May 20 07:43 loop0
brw-r--r-- 1 root root 7, 1 Jun 2 13:47 loop1
crw-r--r-- 1 root root 1, 3 May 20 07:42 null
crw-r--r-- 1 root root 5, 0 May 20 07:43 tty
crw-r--r-- 1 root root 4, 1 May 20 07:43 tty1
crw-r--r-- 1 root root 1, 5 May 20 07:42 zero
./etc:
total 3
-rw-r--r-- 1 root root 2539 May 20 07:43 ld.so.cache
./lib:
total 649
lrwxrwxrwx 1 root root 18 May 27 08:08 ld-linux.so.1 -&gt; ld-linux.so.1.7.14
-rwxr-xr-x 1 root root 21367 May 20 07:44 ld-linux.so.1.7.14
lrwxrwxrwx 1 root root 14 May 27 08:08 libc.so.5 -&gt; libc.so.5.3.12
-rwxr-xr-x 1 root root 583795 May 20 07:44 libc.so.5.3.12
./lost+found:
total 0
./mnt:
total 0
</verb></tscreen>
The only complex steps about this are the devices in <tt>dev</tt>. Use the
<tt>mknod</tt> program to create them, use the existing devices in <tt>/dev</tt>
as a template to get the required parameters.
<bf>The /linuxrc file</bf>
The <tt>/linuxrc</tt> file on the initial ramdisk is required to do all of the
preparations so that the loopback device can be used for the root partition when
it exits.
<p>
The example below tries to mount <tt>/dev/hda1</tt> as an msdos partition and
if it succeeds then sets up the files <tt>/linux/linuxdsk.img</tt> as
<tt>/dev/loop0</tt> and <tt>/linux/linuxswp.img</tt> as <tt>/dev/loop1</tt>.
<p>
<tscreen><verb>
#!/bin/sh
echo INITRD: Trying to mount /dev/hda1 as msdos
if /bin/mount -n -t msdos /dev/hda1 /mnt; then
echo INITRD: Mounted OK
/bin/losetup /dev/loop0 /mnt/linux/linuxdsk.img
/bin/losetup /dev/loop1 /mnt/linux/linuxswp.img
exit 0
else
echo INITRD: Mount failed
exit 1
fi
</verb></tscreen>
The first device <tt>/dev/loop0</tt> will become the root device and the second
one <tt>/dev/loop1</tt> will become the swap space.
<p>
If you want to be able to write to the DOS partition as a non-root user when you
have finished then you should use <tt>mount -n -t msdos /dev/hda1 /mnt -o
uid=0,gid=0,umask=000,quiet</tt> instead. This will map all accesses to the DOS
partition to root and set the permissions appropriately.
<sect1>Creating The Root Device
<p>
The root device that you will be using is the file <tt>linuxdsk.img</tt>. You
will need to create this in the same way that the initial ramdisk was created,
but bigger. You can install any Linux installation that you like onto this
disk.
<p>
The easiest way might be to copy an existing Linux installation into it. An
alternative is to install a new Linux installation onto it.
<p>
Assuming that you have done this, there are some minor changes that you must
make.
<p>
The <tt>/etc/fstab</tt> file must reference the root partition and the
swap using the two loopback devices that are setup on the initial ramdisk.
<p>
<tscreen><verb>
/dev/loop0 / ext2 defaults 1 1
/dev/loop1 swap swap defaults 1 1
</verb></tscreen>
This will ensure that when the real root device is used the kernel will not be
confused about where the root device is. It will also allow the swap space to
be added in the same way a swap partition is normally used. You should remove
any other reference to a root disk device or swap partition.
<p>
If you want to be able to read the DOS partition after Linux has started then
you will need to make a number of extra small changes.
<p>
Create a directory called <tt>/initrd</tt>, this is where the initial ramdisk
will be mounted once the loopback root filesystem is mounted.
<p>
Create a symbolic link called <tt>/DOS</tt> that points to <tt>/initrd/mnt</tt>
where the real DOS parition will be mounted.
<p>
Add a line into the rc file that mounts the disks. This should run the command
<tt>mount -f -t msdos /dev/hda1 /initrd/mnt</tt>, this will create a 'fake'
mount of the DOS partition so that all programs (like <tt>df</tt>) will know that
the DOS partition is mounted and where to find it. If you used different
options in the <tt>/linuxrc</tt> file that obviously you should use them here
also.
<p>
There is no need to have a Linux kernel on this root device since that is
already loaded earlier. If you are using modules however then you should
include them on this device as normal.
<sect1>Creating the Swap Device
<p>
The root device that you will be using is the file <tt>linuxswap.img</tt>. The
swap device is very simple to create. Create an empty file as was done for the
initial ramdisk and then run <tt>mkswap linuxswap.img</tt> to intialise it.
<p>
The size of the swap space will depend on what you plan to do with the installed
system, but I would recommend between 8MB and the amount of RAM that you have.
<sect1>Creating the MSDOS Directory
<p>
The files that are going to be used need to be moved onto the DOS partition.
<p>
The files that are required in the DOS directory called <tt>C:\LINUX</tt> are
the following:
<itemize>
<item><tt>LINUXDSK.IMG</tt> The disk image that will become the root device.
<item><tt>LINUXSWP.IMG</tt> The swap space.
</itemize>
<sect1>Creating the Boot Floppy
<p>
The boot floppy that is used is just a normal DOS format bootable floppy.
<p>
This is created using <tt>format a: /s</tt> from DOS.
<p>
Onto this disk you will need to create an <tt>AUTOEXEC.BAT</tt> file (as below)
and copy the kernel, compressed initial ramdisk and <tt>LOADLIN</tt> executable.
<itemize>
<item><tt>AUTOEXEC.BAT</tt> The DOS automatically executed batch file.
<item><tt>LOADLIN.EXE</tt> The <tt>LOADLIN</tt> program executable.
<item><tt>ZIMAGE</tt> The Linux kernel.
<item><tt>INITRDGZ.IMG</tt> The compressed initial ramdisk image.
</itemize>
The <tt>AUTOEXEC.BAT</tt> file should contain just one line as below.
<tscreen><verb>
\loadlin \zImage initrd=\initrdgz.img root=/dev/loop0 ro
</verb></tscreen>
This specifies the kernel image to use, the initial ramdisk image, the root
device after the initial ramdisk has finished and that the root partition is to
be mounted read-only.
<sect>Booting the System
<p>
To boot from this new root device all that is required is that the floppy disk
prepared as described above is inserted for the PC to boot from.
<p>
You will see the following sequence of events.
<enum>
<item>DOS boots
<item>AUTOEXEC.BAT starts
<item>LOADLIN is run
<item>The Linux kernel is copied into memory
<item>The initial ramdisk is copied into memory
<item>The Linux kernel is started running
<item>The <tt>/linuxrc</tt> file on the initial ramdisk is run
<item>The DOS partition is mounted and the root and swap devices set up
<item>The boot sequence continues from the loopback device
</enum>
When this is complete you can remove the boot floppy and use the Linux system.
<sect1>Possible Problems With Solutions
<p>
There are a number of stages where this process could fail, I will try to
explain what they are and what to check.
<p>
DOS booting is easy to recognise by the message that it prints <tt>MS-DOS
Starting ...</tt> on the screen. If this is not seen then the floopy disk is
either not-bootable or the PC is not bootable from the floppy disk drive.
<p>
When the <tt>AUTOEXEC.BAT</tt> file is run the commands in it should be echoed
to the screen by default. In this case there is just the single line in the
file that starts <tt>LOADLIN</tt>.
<p>
When <tt>LOADLIN</tt> executes it will do two very visible things, firstly it
will load the kernel into memory, secondly it will copy the ramdisk into memory.
Both of these are indicated by a <tt>Loading...</tt> message.
<p>
The kernel starts by uncompressing itself, this can give <bf>crc</bf> errors if
the kernel image is corrupted. Then it will start running the initialisation
sequence which is very verbose with diagnostic messages. Loading of the initial
ramdisk device is also visible during this phase.
<p>
When the <tt>/linuxrc</tt> file is run there is no diagnostic messages, but you
can add these yourself as an aid to debugging. If this stage fails to set up
the loopback device as the root device then you may see a message that there is
no root device and the kernel aborts.
<p>
The normal boot sequence of the new root device will now continue and this is
quite verbose. There may be problems about the root device being mounted
read-write, but the <tt>LOADLIN</tt> command line option '<tt>ro</tt>' should
stop that. Other problems that can occur are that the boot sequence is confused
about where the root device is, this is probably due to a problem with
<tt>/etc/fstab</tt>.
<p>
When the boot sequence has completed, the remaining problem is that programs are
confused about whether the DOS partition is mounted or not. This is why it is a
good idea to use the fake mount command described earlier. This makes life a
lot easier if you want to access the files on the DOS device.
<sect1>Reference Documents
<p>
The documents that I used to create my first loopback root filesystem were:
<p>
<itemize>
<item>The Linux kernel source, in particular <tt>init/main.c</tt>
<item>The Linux kernel documentation, in particular
<tt>Documentation/initrd.txt</tt> and <tt>Documentation/ramdisk.txt</tt>.
<item>The <tt>LILO</tt> documentation.
<item>The <tt>LOADLIN</tt> documentation
</itemize>
<sect>Other Loopback Root Device Possibilities
<p>
Once the principle of booting a filesystem in a file on a DOS partition has been
established there are many other things that you can now do.
<sect1>DOS Hard-disk Only Installation
<p>
If it is possible to boot Linux from a file on a DOS harddisk by using a boot
floppy then it is obviously also possible to do it using the harddisk itself.
<p>
A configuration boot menu can be used to give the option of running
<tt>LOADLIN</tt> from within the <tt>AUTOEXEC.BAT</tt>. This will give a much
faster boot sequence, but is otherwise identical.
<sect1>LILO Booted Installation
<p>
Using <tt>LOADLIN</tt> is only one option for booting a Linux kernel. There is
also <tt>LILO</tt> that does much the same but without needing DOS.
<p>
In this case the DOS format floppy disk can be replaced by an ext2fs format one.
Otherwise the details are very similar, with the kernel and the initial ramdisk
being files on that disk.
<p>
The reason that I chose the <tt>LOADLIN</tt> method is that the arguments that
need to be given to <tt>LILO</tt> are slightly more complex. Also it is more
obvious to a casual observer what the floppy disk is since it can be read under
DOS.
<sect1>VFAT / NTFS Installation
<p>
I have tried the NTFS method, and have had no problems with it. The NTFS
filesystem driver is not a standard kernel option in version 2.0.x, but is
available as a patch from <htmlurl
url="http://www.informatik.hu-berlin.de/~loewis/ntfs/"
name="http://www.informatik.hu-berlin.de/~loewis/ntfs/">. In version 2.2.x the
NTFS driver is included as standard in the kernel.
<p>
The only changes for the VFAT or NTFS options are in the initial ramdisk, the
file <tt>/linuxrc</tt> needs to mount a file system of type vfat or ntfs rather
that msdos.
<p>
I know of no reason why this should not also work on a VFAT partition.
<sect1>Installing Linux without Re-partitioning
<p>
The process of installing Linux on a PC from a standard distribution requires
booting from a floppy disk and re-partitioning the disk. This stage could
instead be accomplished by a boot floppy that creates an empty loopback device
and swap file. This would allow the installation to proceed as normal, but it
would install into the loopback device rather than a partition.
<p>
This could be used as an alternative to a <tt>UMSDOS</tt> installation, it would
be more efficient in disk usage since the minimum allocation unit in the ext2
filesystem is 1kB instead of up to 32kB on a DOS partition. It can also be used
on VFAT and NTFS formatted disks which are otherwise a problem.
<sect1>Booting From a Non-bootable device
<p>
This method can also be used to boot a Linux system from a device that is not
normally bootable.
<p>
<itemize>
<item>CD-Rom
<item>Zip Disks
<item>Parallel port disk drives
</itemize>
Obviously there are many other devices that could be used, NFS root filesystems
are already included in the kernel as an option, but the method described here
might also be used instead.
</article>

601
LDP/retired/MGR-HOWTO.sgml Normal file
View File

@ -0,0 +1,601 @@
<!doctype linuxdoc system>
<article>
<title>The MGR Window System HOWTO
<author>Vincent Broman
</author>
<date>v0.1, 1996-05-30
<abstract>
Information on the installation, configuration and running of the MGR Window
System.
<p>
<bf>Archived Document Notice:</bf> This document has been archived by the LDP
because it does not apply to modern Linux systems. It is no longer
being actively maintained.
</p>
</abstract>
<toc>
<sect>This HOWTO
<p><verb>
Copyright Vincent Broman 1995.
Permission granted to make and distribute copies of this HOWTO
under the conditions of the GNU General Public License.</verb>
<sect1>Archiving
<p>
This HOWTO is archived in
<tt>ftp://archimedes.nosc.mil/pub/Mgr/MGR-HOWTO.sgml</tt>,
and also distributed from
<tt>ftp://sunsite.unc.edu/pub/Linux/docs/HOWTO/MGR-HOWTO</tt>.
In nearby directories the same document may appear in
alternate formats like <tt>MGR-HOWTO.txt</tt>.
<sect1>Authentication
<p>
Copies of the MGR distribution due to Broman should be accompanied
by PGP signature files, signed by "Vincent Broman &lt;broman@nosc.mil&gt;".
<sect1>Credit for the HOWTO
<p>
While Vincent Broman first put together this HOWTO,
much of the information and text was obtained from FAQs,
READMEs, etc. written by Stephen Uhler, Michael Haardt,
and other public-spirited net-persons.
Email corrections and suggested changes to <tt>broman@nosc.mil</tt>.
Uhler was the main architect of <bf>MGR</bf> -- see the Credit section below.
<sect>What is the MGR window system?
<p>
<sect1>Function
<p>
<bf>MGR</bf> (ManaGeR) is a graphical window system.
The <bf>MGR</bf> server
provides a builtin window manager and windowed graphics terminal
emulation on color and monochrome bitmap displays. <bf>MGR</bf> is
controlled by mousing pop-up menus, by keyboard interaction, and by
escape sequences written on pseudo-terminals by client software.
<p>
<bf>MGR</bf> provides each client window with: termcap-style terminal
control functions, graphics primitives such as line and circle
drawing; facilities for manipulating bitmaps, fonts, icons, and
pop-up menus; commands to reshape and position windows; and a
message passing facility enabling client programs to rendezvous
and exchange messages. Client programs may ask to be informed
when a change in the window system occurs, such as a reshaped
window, a pushed mouse button, or a message sent from another
client program. These changes are called events.
<bf>MGR</bf> notifies a
client program of an event by sending it an ASCII character string
in a format specified by the client program. Existing
applications can be integrated into the windowing environment
without modification by having <bf>MGR</bf> imitate keystrokes in response
to user defined menu selections or other events.
<sect1>Requirements
<p>
<bf>MGR</bf> currently runs on Linux, FreeBSD,
Sun 3/4 workstations with SunOS, and
Coherent. Various older versions of <bf>MGR</bf> run on the Macintosh,
Atari ST MiNT, Xenix, 386-Minix, DEC 3100, and the 3b1 Unix-pc.
Many small, industrial, real-time systems under OS9 or Lynx in Europe
use (another variant of) Mgr for their user interface.
The programming interface is implemented in C and in ELisp,
although supporting clients written in other languages is quite
easy.
Running <bf>MGR</bf> requires much less in resources than X, or even gcc.
It does not have the user-base, software repertory, or high-level
libraries of X or MS-Windows, say, but it is quite elegant
and approachable.
It has been said that <bf>MGR</bf> is to X as Unix was to Multics.
<sect1>How do MGR, X11, and 8.5 compare?
<p>
<bf>MGR</bf> consists of a server with builtin window manager and terminal
emulator, and clients which run in this terminal emulator and use it
to communicate with the server. No resource multiplexing is done.
X11 consists of a server and clients, which usually connect to the
server using a socket. All user visible things like terminal
emulators, window managers etc are done using clients. No resource
multiplexing is done.
8.5, the Plan 9 window system, is a resource multiplexer, as each
process running in a window can access <tt>/dev/bitblt</tt>,
<tt>/dev/mouse</tt> and
<tt>/dev/kbd</tt> in its own namespace. These are multiplexed to the
<tt>/dev/bitblit</tt>, <tt>/dev/mouse</tt> and <tt>/dev/kbd</tt>
in the namespace of 8.5.
This approach allows one to run 8.5 in an 8.5 window,
a very clean design. 8.5 further has an integrated window manager
and terminal emulator.
<sect>Installing MGR
<p>
The latest source distribution can be FTPed from the directory
<tt>ftp://archimedes.nosc.mil/pub/Mgr/69</tt>
or Mosaiced from <tt>http://archimedes.nosc.mil/Mgr/69</tt>.
The same should be found at
<tt>ftp://sunsite.unc.edu/pub/Linux/apps/MGR</tt> and its mirrors.
Older versions of this distribution
from Haardt can be found on <tt>tsx-11.mit.edu</tt> and perhaps elsewhere.
Pre-Linux versions of <bf>MGR</bf> from Uhler and others have been found at
<tt>ftp://bellcore.com/pub/mgr</tt>, but I think they are gone now.
I have saved a copy of everything about <bf>MGR</bf> seen on the Internet,
but I am not aware of anything weighty
that is missing from this Linux/Sun distribution.
<bf>MGR</bf> has been through a lot of versions and releases,
but the current *Linux* version number is 0.69. This version number
could jump to 1.0 when stable 256-color VGA code for Linux appears
(for more than one video card type).
RCS version numbers have increased from Bellcore's 4.3 up to our 4.13 now.
Required tools to build this distribution of <bf>MGR</bf> are m4 (GNU, or
perhaps another supporting the -D option), make (GNU, or perhaps
another supporting include) and *roff for the docs. Also sh,
awk, and POSIX install. Binary distributions are not assembled often
so you need an ANSI C compiler environment, e.g. gcc.
A Linux installation requires Linux 0.99.10 or better
(1.2.13 is what I actually test on now),
an HGC, EGA, VGA, or SVGA graphics card, and a mouse. Mouses supported
are: serial Microsoft mouse, serial MouseSystems 3 and 5 byte
mouse, serial MMSeries mouse, serial Logitech mouse, PS/2 mouse,
or a bus mouse.
With Buckey (Meta) hot keys enabled, even a mouseless system could
do a certain amount of useful work under <bf>MGR</bf>.
The VGA 640x480 monochrome graphics mode is
supported out of the box, as is 640x350 and 640x200. To run
800x600, or other modes that your BIOS can initialize and which
do not require bank-switching, you need to run a small program
(supplied as <tt>src/vgamisc/regs.exe</tt>)
under DOS or an emulator to read the VGA registers
and write a header file which you place in the
directory <tt>src/libbitblit/linux</tt>,
so that it can be <tt>#include</tt>'d
by the <tt>vga.c</tt> file there.
Samples of these files are supplied, but please create your own.
Some VGA cards can use 128k
windows, and these might run higher monochrome resolutions.
The Linux-colorport code also runs in the standard
320x200x256 color VGA mode without difficulty, because no bank switching
is required. If you think of how few 64000 pixels is, you would
realize this color mode is quite limited.
Non-fast, but simple, bank-switching code has
been added in version 0.65, and it works with a Tseng ET4000 card
in 640x480x256 and 800x600x256 modes. The S3 code does not
work in super VGA resolutions, yet. Supporting new super VGA cards
requires writing one function to switch banks and then making sure that
the desired screen mode can be initialized from a register dump,
possibly with hand-tweaking. The Linux color servers generally
mangle the screen fonts, necessitating use of restorefont as in runx.
If someone were to extract the VGA initialization code out of X,
this might make MGR work on a lot more color systems.
Suns with SunOS 4.1.2+ and <tt>bwtwo</tt>, <tt>cgthree</tt>, or
<tt>cgsix</tt> frame buffers are supported.
Their speed handling color is good.
Coherent installations should refer to the
<tt>Versions/README.Coh</tt> file in the source distribution.
Porting the
latest-and-greatest <bf>MGR</bf> to another POSIX-like system which
provides <tt>select()</tt> and pty's and direct access to a bitmapped
frame-buffer ought to be straightforward, just implementing the
<tt>libbitblit</tt> library based on the <tt>sunmono</tt> or
<tt>colorport</tt> code, say.
If you want to install everything, you need 7 MB disk space for
binaries, fonts, manual pages etc. The sources are about 4.5 MB,
plus object files during compilation.
Normally, <tt>/usr/mgr</tt> should be either the directory or a link to the
directory where you install <bf>MGR</bf> stuff for runtime use. Typing
<tscreen><verb>
cd /usr/mgr; tar xvfz whereveryouputit/mgrusr-0.69.tgz
</verb></tscreen>
and optionally
<tscreen><verb>
cd /usr/mgr; tar xvfz wherever/morefonts-0.69.tgz
</verb></tscreen>
will unpack these. The source can be put anywhere, e.g. typing
<tscreen><verb>
cd /usr/src/local/mgr; tar xvfz wherever/mgrsrc-0.69.tgz
</verb></tscreen>
to unpack the sources from <tt>archimedes.nosc.mil</tt>.
The source tree can be compiled from one top-level Makefile which
invokes lower-level Makefiles, all of which &dquot;include&dquot;
a <tt>&dquot;Configfile&dquot;</tt>
at the top level. The <tt>Configfile</tt> is created by an interactive sh
script named <tt>Configure</tt>, which asks you questions,
then runs m4 on a <tt>Configfile.m4</tt>.
So you type something like this:
<tscreen><verb>
chdir /usr/src/local/mgr
sh ./Configure
make first
make depend
make install
make clean
</verb></tscreen>
It might be wise, before running make, to eyeball the <tt>Configfile</tt>
generated by the <tt>Configure</tt> script, checking that it looks reasonable.
(At least one m4 poops out (Sun <tt>/usr/bin/m4</tt>),
creating a very short <tt>Configfile</tt>.
If this happens, try hand editing a copy of <tt>Configfile.sun</tt> or
<tt>Configfile.lx</tt>)
One can also <tt>make all</tt> in any directory with a Makefile
as soon as the libraries have been compiled and installed.
The server, libraries, and some clients have been linted, but several
clients are K&amp;R C code that generates many compiler warnings.
<p>
Several flags in MGRFLAGS can be added/omitted in the Configfile
to change some
optional features in the server, viz:
<descrip>
<tag/-DWHO/ muck utmp file so &dquot;who&dquot; works
<tag/-DVI/ code for clicking the mouse in vi moving the cursor
<tag/-DDEBUG/ enable debugging output selectable with -d options.
<tag/-DFASTMOUSE/ XOR the mouse track
<tag/-DBUCKEY/ for hot-key server commands without mousing
<tag/-DPRIORITY/ for priority window scheduling instead of
round-robin; the active window gets higher priority
<tag/-DCUT/ for cut/paste between windows and a global snarf buffer
<tag/-DMGR_ALIGN/ forces window alignment for fast scrolling (monochrome)
<tag/-DKILL/ kills windows upon tty i/o errors
<tag/-DSHRINK/ use only some of the screen (&dollar;MGRSIZE in environment)
<tag/-DNOSTACK/ don't permit event stacking
<tag/-DBELL/ audibly ring the bell
<tag/-DKBD/ read <tt>mgr</tt> input from the sun kbd, instead of stdin.
This permits redirection of console msgs to a window.
<tag/-DFRACCHAR/ fractional character movement for proportional fonts
<tag/-DXMENU/ extended menu stuff (experimental)
<tag/-DMOVIE/ movie making extension which logs all operations to a
file for later replay -- not quite working under Linux
<tag/-DEMUMIDMSBUT/ Emulate a missing middle mouse button by chording
</descrip>
Not all combinations of these options have been tested on all systems.
The BITBLITFLAGS macro should contain <tt>-DBANKED</tt> if you're trying
out the super VGA color.
<p>
C code for the static variables in the server containing icons and fonts
is generated by a translator from icon and font files.
Not all the clients are compiled and installed by the Makefiles.
Clients found under <tt>src/clients</tt> having capitalized names or
not compiled by the supplied Makefiles may have problems compiling
and/or running, but they may be interesting to hack on.
Most of the screen drivers found under the <tt>libbitblit</tt> directory are
of mainly archeological interest. Grave robbing can be profitable.
<p>
At some point check that your <tt>/etc/termcap</tt> and/or
<tt>terminfo</tt> file
contain entries for <bf>MGR</bf> terminals such as found in the <tt>misc</tt>
directory. If all your software checks &dollar;TERMCAP in the environment,
this is not needed, as long as you run <tt>eval `set_termcap`</tt>
in each window.
<p>
<bf>MGR</bf> works better if run setuid root, because it wants to chown
ptys and write in the utmp file. This helps the ify iconifier
client work better and the event passing mechanism be more secure.
On Linux, root permissions are <em>required</em> in order to do in/out on the
screen device. Otherwise, you decide whether to trust it.
<p>
In versions around 0.62 there are troubles on the Sun with using
the csh as the default shell. Programs seem to run in a different
process group than the foreground process group of the window's pty,
in contradiction to man pages and posix specs.
There is no trouble with bash, sh, or rc. Ideas why?
<sect>Running MGR
<p>
The only file <em>required</em> in an <bf>MGR</bf> installation is the server
itself. That would give you terminal emulator windows with shells
running in them and cutting and pasting with the mouse,
but no nice clocks, extra fonts, fancy graphics,
etc. Depending on options, a monochrome server needs about 200K of RAM
plus dynamic space for windows, bitmaps, etc.
<p>
If <tt>/usr/mgr/bin</tt> is in your PATH,
then just type &dquot;<tt>mgr</tt>&dquot; to start up.
After enjoying the animated startup screen, press any key.
When the hatched background and mouse pointer appear, hold down
the left mouse button, highlight the &dquot;new window&dquot; menu item, and
release the button. Then drag the mouse from corner to corner
where you want a window to appear. The window will have your
default shell running in it. Hold down the left mouse button over
an existing window to see another menu for doing things to that
window. Left-clicking on an obscured window raises it to the top.
The menu you saw that pops-up over the empty background
includes the quit command.
For people with a two button mouse:
press both buttons together to emulate the missing middle button
used by some clients.
<p>
The quit submenu includes the &dquot;really quit&dquot; option,
a suspend option which should only be used if you run a
job-control shell, and a screen saver and locker option, which
waits for you to type your login password when you come back
to your machine.
<p>
When trying to run <bf>MGR</bf>, if you get:
<descrip>
<tag/can't find the screen/
make sure you have a <tt>/dev</tt> entry for your display device,
e.g. on
a Sun <tt>/dev/bwtwo0</tt>. If not, as root cd to <tt>/dev</tt>, and type
&dquot;MAKEDEV bwtwo0&dquot;. Otherwise, you might need the
<tt>-S/dev/bwtwo0</tt>
or (on Linux) the <tt>-S640x480</tt> command line option when starting <tt>mgr</tt>.
On Linux, you might also make sure that <tt>/usr/mgr/bin/mgr</tt> was
installed setuid root.
<tag/can't find the mouse/
make sure <tt>/dev/mouse</tt> exists, usually as a symbolic link to the
real device name for your mouse. If you haven't permission to
write in <tt>/dev</tt>, then something like a <tt>-m/dev/cua0</tt>
option can be
given when starting <tt>mgr</tt>. Also, make sure you've supplied the
right mouse protocol choice when you configured <tt>mgr</tt>. The mouse
may speak Microsoft, even if that is not the brand name.
<tag/can't get a pty/
make sure all of <tt>/dev/[tp]ty[pq]?</tt>
are owned by root, mode 666,
and all programs referenced with the &dquot;shell&dquot; option in
your <tt>.mgrc</tt> startup file (if any) exist and are executable.
<tag/none but the default font/
make sure <bf>MGR</bf> is looking in the right
place for its fonts. Check the <tt>Configfile</tt> in the source or
see whether a <tt>-f/usr/mgr/font</tt> option to <tt>mgr</tt> fixes the problem.
<tag/completely hung (not even the mouse track moves)/
login to your machine from another terminal (or rlogin) and kill the
<tt>mgr</tt> process.
A buckey-Q key can quit <bf>MGR</bf> if the keyboard still works.
</descrip>
<sect1>Applications not aware of MGR
<p>
Any tty-oriented application can be run in an <bf>MGR</bf> window
without further ado. Screen-oriented applications using
termcap or curses can get the correct number of lines and
columns in the window by your using <tt>shape(1)</tt>
to reshape the window or using
<tt>set_termcap(1)</tt> to obtain the correct termcap entry.
<sect1>MGR Applications (clients) distributed with the server
<p>
<descrip>
<tag/bdftomgr/ converts some BDF fonts to MGR fonts
<tag/browse/ an icon browser
<tag/bury/ bury this window
<tag/c_menu/ vi menus from C compiler errors
<tag/clock/ digital display of time of day
<tag/clock2/ analog display of time of day
<tag/close/ close this window, iconify
<tag/color/ set the foreground and background color for text in this window
<tag/colormap/ read or write in the color lookup table
<tag/cursor/ change appearance of the character cursor
<tag/cut/ cut text from this window into the cut buffer
<tag/cycle/ display a sequence of icons
<tag/dmgr/ crude ditroff previewer
<tag/fade/ fade a home movie script from one scene to another
<tag/font/ change to a new font in this window
<tag/gropbm/ a groff to PBM driver using Hershey fonts
<tag/hpmgr/ hp 2621 terminal emulator
<tag/ico/ animate an icosahedron or other polyhedron
<tag/iconmail/ notification of mail arrival
<tag/iconmsgs/ message arrival notification
<tag/ify/ iconify and deiconify windows
<tag/loadfont/ load a font from the file system
<tag/maze/ a maze game
<tag/mclock/ micky mouse clock
<tag/menu/ create or select a pop-up menu
<tag/mgr/ bellcore window system server and window manager
<tag/mgrbd/ boulder-dash game
<tag/mgrbiff/ watch mailbox for mail and notify
<tag/mgrload/ graph of system load average
<tag/mgrlock/ lock the console
<tag/mgrlogin/ graphical login controller
<tag/mgrmag/ magnify a part of the screen, optionally dump to file
<tag/mgrmail/ notification of mail arrival
<tag/mgrmode/ set or clear window modes
<tag/mgrmsgs/ message arrival notification
<tag/mgrplot/ Unix &dquot;plot&dquot; graphics filter
<tag/mgrsclock/ sandclock
<tag/mgrshowfont/ browse through mgr fonts
<tag/mgrsketch/ a sketching/drawing program
<tag/mgrview/ view mgr bitmap images
<tag/mless/ start up less/more in separate window, menu added for less
<tag/mnew/ startup up any program in a separate, independent window
<tag/mphoon/ display the current phase of the moon
<tag/mvi/ start up vi in a separate window, with mouse pointing
<tag/oclose/ (old) close a window
<tag/omgrmail/ (old) notification of mail arrival
<tag/pbmrawtomgr, pgmrawtomgr, ppmrawtomgr/ convert raw PBM/PGM/PPM image files to mgr bitmap format
<tag/pbmstream/ split out a stream of bitmaps
<tag/pbmtoprt/ printer output from PBM
<tag/pgs/ ghostscript patch and front end, a PS viewer
<tag/pilot/ a bitmap browser, or image viewer
<tag/resetwin/ cleanup window state after client crashes messily
<tag/rotate/ rotate a bitmap 90 degrees.
<tag/screendump/ write graphics screen dump to a bitmap file
<tag/set_console/ redirect console messages to this window
<tag/set_termcap/ output an appropriate TERM and TERMCAP setting
<tag/setname/ name a window, for messages and iconifying
<tag/shape/ reshape this window
<tag/square/ square this window
<tag/squeeze/ compress mgr bitmap using run-length encoding
<tag/startup/ produce a skeleton startup file for current window layout
<tag/texmgr/ TeX dvi file previewer
<tag/text2font, font2text/ convert between mgr font format and text dump
<tag/unsqueeze/ uncompress mgr bitmap using run length encoding
<tag/vgafont2mgr, mgrfont2vga/ convert between mgr font format and VGA
<tag/window_print/ print an image of a window
<tag/zoom/ an icon editor
<tag/bounce, grav, grid, hilbert, mgreyes, stringart, walk/ graphics demos
</descrip>
<sect1>MGR-aware clients distributed separately, see &dquot;SUPPORT&dquot; file
<p>
<descrip>
<tag/calctool/ on-screen calculator
<tag/chess/ frontend to <tt>/usr/games/chess</tt>
<tag/gnu emacs/ editor with <tt>lisp/term/mgr.el</tt> mouse &amp; menu support
<tag/gnuplot/ universal scientific data plotting
<tag/metafont/ font design and creation
<tag/origami/ folding editor
<tag/pbmplus/ portable bitmap format conversions, manipulations
<tag/plplot/ slick scientific data plotting
</descrip>
<p>
The Emacs support in <tt>misc/mgr.el</tt> and <tt>misc/mailcap</tt>
includes very usable MIME support, via Rmail and metamail.
<p>
A general image viewer could be cobbled together from <tt>pilot</tt>
and the netPBM filters, but I have not taken the time to do it.
<sect>Programming for MGR
<p>
The <bf>MGR</bf> programmers manual, the C language applications interface,
is found in the doc directory in troff/nroff form. It covers
general concepts, the function/macro calls controlling the server,
a sample application, with an index and glossary.
Porting client code used with older versions of <bf>MGR</bf> sometimes
requires the substitution of
<tscreen><verb>
#include <mgr/mgr.h>
</verb></tscreen>
for
<tscreen><verb>
#include <term.h>
#include <dump.h>
</verb></tscreen>
and clients using old-style B_XOR, B_CLEAR, et al instead of
BIT_XOR, BIT_CLR, et al can be accommodated by writing
<tscreen><verb>
#define OLDMGRBITOPS
#include <mgr/mgr.h>
</verb></tscreen>
Compiling client code generally requires compiler options like
the following.
<tscreen><verb>
-I/usr/mgr/include -L/usr/mgr/lib -lmgr
</verb></tscreen>
One can get some interactive feel for the <bf>MGR</bf> server functions by
reading and experimenting with the <tt>mgr.el</tt> terminal driver for GNU
Emacs which implements the <bf>MGR</bf> interface library in ELisp.
The usual method of inquiring state from the server has the
potential of stumbling on a race condition if the client also
expects a large volume of event notifications. The problem arises
if an (asynchronous) event notification arrives when a
(synchronous) inquiry response was expected. If this arises in
practice (unusual) then the <bf>MGR</bf> state inquiry functions would have
to be integrated with your event handling loop.
The only major drawing function missing from the <bf>MGR</bf> protocol, it
seems, is an area fill for areas other than upright rectangles.
There is new code for manipulating the global colormap, as well as
(advisory) allocation and freeing of color indices owned by windows.
If you are thinking of hacking on the server, you can find the mouse
driver in <tt>mouse.*</tt> and <tt>mouse_get.*</tt>,
the grotty parts of the keyboard
interface in <tt>kbd.c</tt>, and the interface to the display in the
<tt>src/libbitblit/*</tt> directories. The main procedure, much
initialization, and the top level input loop are in <tt>mgr.c</tt>, and the
interpretation of escape sequences is in <tt>put_window.c</tt>.
<sect>More documentation
<p>
The programmer's manual is essential for concepts.
Nearly all the clients supplied come with a man page which is installed
into <tt>/usr/mgr/man/man1</tt> or <tt>man6</tt>.
Other useful man pages are <tt>bitblit.3</tt>, <tt>font.5</tt>, and
<tt>bitmap.5</tt>.
There is some ambiguity in the docs in distinguishing the
internal bitmap format found in your frame-buffer and the external
bitmap format found in files, e.g. icons.
The <tt>mgr.1</tt> man page covers command line options, commands in
the <tt>~/.mgrc</tt> startup file, mouse and menu interaction with the server,
and hot-key shortcuts available on systems with such hot-keys.
Many of the fonts in <tt>/usr/mgr/font/*</tt> are described to some
extent in <tt>/usr/mgr/font/*.txt</tt>, e.g. <tt>/usr/mgr/font/FONTDIR.txt</tt>
gives X-style font descriptions for the fonts obtained
in .bdf format. Font names end in <tt>WxH</tt>, where <tt/W/ and <tt/H/
are the
decimal width and height in pixels of each character box.
<sect>Credit for MGR
<p>
Stephen Uhler, with others working at Bellcore, was the original
designer and implementer of <bf>MGR</bf>, so Bellcore has copyrighted much
of the code and documentation for <bf>MGR</bf> under the following conditions.
<verb>
* Permission is granted to copy or use this program, EXCEPT that it
* may not be sold for profit, the copyright notice must be reproduced
* on copies, and credit should be given to Bellcore where it is due.
</verb>
One required showing of the copyright notice is the startup title screen.
Other credits to:
<itemize>
<item> Stephen Hawley for his wonderful icons.
<item> Tommy Frandsen for the VGA linux library.
<item> Tom Heller for his Gasblit library.
<item> Andrew Haylett for the Mouse driver code.
<item> Dan McCrackin for his gasblit->linux patches.
<item> Dave Gymer, dgymer@gdcarc.co.uk, for the Startrek effect fix.
<item> Alex Liu for first releasing a working Linux version of <bf>MGR</bf>.
<item> Lars Aronsson (aronsson@lysator.liu.se) for text2font and
an ISO8859-1 8-bit font.
<item> Harry Pulley (hcpiv@grumpy.cis.uoguelph.ca,
hcpiv@snowhite.cis.uoguelph.ca) for the Coherent port.
<item> Vance Petree &amp; Grant Edwards &amp; Udo Munk for their work on Hercules.
<item> Udo Munk for his work on serial mouse initialization &amp; select.
<item> Norman Bartek &amp; Hal Snyder at Mark Williams Co. for their help
with some bugs &amp; with Coherent device drivers.
<item> Extra thanks to Zeyd Ben Halim for lots of helpful patches,
especially the adaptation of selection.
<item> Bradley Bosch, brad@lachman.com, for lots of patches from his 3b1
port, which fix bugs and implement new and desirable features.
<item> Andrew Morton, applix@runxtsa.runx.oz.au, who first wrote the
cut-word code.
<item> Kapil Paranjape, kapil@motive.math.tifr.res.in, for the EGA
support.
<item> Michael Haardt for MOVIE support fixes, bug fixes, separation of the
libbitblit code into output drivers, expansion of the libmgr, and
origami folding of the code.
<item> Yossi Gil for many fonts.
<item> Carsten Emde, carsten@thlmak.pr.net.ch, for mphoon.
<item> Vincent Broman for middle mouse-button emulation, linting, Sun cgsix
support, VGA colormap acess, integration of the sunport code
into Haardt's layering scheme, font gathering, the screen saver,
and continued maintenance.
<item> Kenneth Almquist, ka@socrates.hr.att.com, for helpful bug reports.
<item> Tim Pierce, twpierce@midway.uchicago.edu, for the port to FreeBSD
2.0R with Trident VGA.
</itemize>
All bitmap fonts from any source are strictly public domain in the
USA. The 583 fixed-width fonts supplied with <bf>MGR</bf> were obtained
from Uhler, the X distribution, Yossi Gil, and elsewhere.
The Hershey vector fonts and the code for rendering them
are probably freely redistributable.
</article>

1651
LDP/retired/MIPS-HOWTO.sgml Normal file
View File

File diff suppressed because it is too large Load Diff

262
LDP/retired/MMBase.sgml Normal file
View File

@ -0,0 +1,262 @@
<!doctype linuxdoc system>
<article>
<title>MMBase Mini-HOWTO: Installation on Debian Woody
<author>Casper Joost Eyckelhof <tt/&lt;joost@dnd.utwente.nl>/ <newline>University of Twente
<date>v0.2, 28 May 2002
<abstract>
This document briefly describes how to set up MMBase on a Debian Gnu/Linux (Woody) system
while using as much default packages as possible.
</abstract>
<toc>
<sect>Introduction<p>
<sect1>Homepage<p>
If you got this document from a Linux HOWTO mirror site or a CD-ROM,
you might want to check back to the <url name="MMBase Mini-HOWTO home
page" url="http://www.dnd.utwente.nl/~joost/mmbase-mini/MMBase-Mini-HOWTO.html"> to see if there's a
newer version around.<p>
This document only covers a very small portion of MMBase installation, for
the official documentation visit <url name="MMBase home page"
url="http://www.mmbase.org">.<p>
<sect1>Disclaimer<p>
No liability for the contents of this documents can be accepted.
Use the concepts, examples and other content at your own risk.<p>
All copyrights are held by their respective owners, unless specifically noted otherwise.
Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark.<p>
Finally, this is my first HOWTO, my first experience with linuxdoc and I am no expert on
MMBase either. I am just trying to share my solutions to some problems I encountered while installing
MMBase on a Debian system.<p>
<sect1>History<p>
0.2 Updated for MMbase 1.5; lost support for apache frontend<p>
0.1 Initial version - Installing MMBase 1.4 on Woody<p>
<sect1>Copyright<p>
Copyright (c) 2001-2002 Casper Joost Eyckelhof, All rights reserved. This is free
documentware; you can redistribute it and/or modify it under the terms of
version 2 or later of the <url name="GNU General Public License"
url="http://www.gnu.org/copyleft/gpl.html">.<p>
<sect1>Acknowledgements<p>
I would like to thank a number of people for helping me during my quest for a clean installation.
Although I do not know their names, their nicknames on irc are: <em>keesj, jdg, flax, scb2</em>.
I hope they forgive me for not trying to find out their real names.<p>
I would also like to thank my employer, the <em>University of Twente</em> for allowing me to write this
document during working hours.
<sect>What is MMBase?<p>
On their website, the authors say the following about it:<p>
<itemize>
<item>MMBase is an opensource publishing system. MMBase can be used to create big websites that can be maintained easily.
<item>MMBase separates content from layout, in this way information can be reused easily.
<item>MMBase is very unique in the way it maintains its information. MMBase creates an object cloud that is a digital representation of the 'real' world objects that are of interest for you.<p>
</itemize><p>
In this document I will describe how to get MMBase running on a Debian Woody System, using
as many standard packages as possible. Though it is very easy to run MMBase using their
automatic installation tools, you will end up with their version of a webserver, servlet engine
and database.<p>
After a few days of playing with my own install, I think I can help others by describing
which choices I made to get things running. I do not claim this is the only way, or the best way!
But it worked for me :)<p>
The version of MMBase used is 1.5. Ofcourse everything might be different with another version.<p>
MMbase can run together with various webservers, databases, servlet engines and JRE's.
The programs/packages/versions I chose are:<p>
<itemize>
<item>MySQL-Server (3.23.49-8)
<item>Tomcat4 (4.0.3-3)
<item>j2sdk1.3 (1.3.1-1) (Java)
<item>imagemagick (4:5.4.4.5-1)
</itemize><p>
Attention: The version numbers are those that were available in
the Woody distribution at the time of writing. Except for Java, which
came from a different location. See <ref id="java" name="Non standard package(s)">.
<p>
Some other options for databases and webservers are described in the
installation notes for MMBase 1.5
<p>
<sect>Prerequisites<p>
You will need a working Debian Woody installation, including apt, and make sure
the following packages are installed and working correctly.
<sect1>Standard packages<p>
<itemize>
<item>tomcat4
<item>mysql-server
<item>imagemagick
</itemize><p>
If these packages are not installed, you can do so by typing
<tscreen><verb>
apt-get install packagename
</verb></tscreen>
where packagename is one of the above.<p>
Note: naturally you will need al dependencies too, but apt will take care of that
automatically.
<sect1>Non standard package(s)<label id="java"><p>
While writing this document, Woody only contains java 1.1, but for MMBase
version 1.2 or higher is needed. I installed the packages from Blackdown.
A list of Blackdown mirrors is at <url name="http://www.blackdown.org/java-linux/mirrors.html"
url="http://www.blackdown.org/java-linux/mirrors.html">.<p>
I added the following to my /etc/apt/sources.list , but the path might be different for different mirrors:
<tscreen><verb>
deb ftp://ftp.nluug.nl/pub/os/Linux/java/jdk/debian woody non-free
</verb></tscreen><p>
After that you can just type
<tscreen><verb>
apt-get install j2sdk1.3
</verb></tscreen><p>
Note: Although it must be possible to have more JRE's installed next to eachother, I wouldn't recommend
it if it's not absolutely neccesary.
<sect>Getting MMBase and setting up some things<p>
<sect1>Getting MMBase<p>
Now that you have all supporting packages up and running (you <em>did</em>
follow the instructions in the previous section, didn't you?) get yourself a copy of MMBase.
As said before, this document describes the works for MMbase version 1.4.<p>
Download MMBase from <url name="http://www.mmbase.org/releases/mmbase-1.5.zip"
url="http://www.mmbase.org/releases/mmbase-1.5.zip"> with a browser, or even easier:
<tscreen><verb>
wget http://www.mmbase.org/releases/mmbase-1.5.zip
</verb></tscreen><p>
From version 1.5 MMBase can be used as an webapp within Tomcat. So I
recommend unpacking the distribution in a temporary directory and copying
the mmbase-webapp/ tree to /var/lib/tomcat4/webapps/.
If MMBase is your only (or main) application on Tomcat, you can also install
it as ROOT, by copying everything from mmbase-webapp/ to /var/lib/tomcat4/webapps/ROOT/.
In this document I will assume that MMBase is unpacked in
/var/lib/tomcat4/webapps/mmbase-webapp/<p>
<sect1>Getting mm.mysql<p>
You will also need mysql.jar (JDBC driver for MySQL) which can be downloaded from
<url name="http://mmmysql.sourceforge.net/" url="http://mmmysql.sourceforge.net/">. <newline>
Make sure you get the binary jar, which means you may have to unjar the
complete distribution first and locate the file mm.mysql-2.0.14-bin.jar
(2.0.14 was the latest release when writing this HOWTO)
Put the file in /var/lib/tomcat4/webapps/mmbase-webapp/WEB-INF/lib/.<p>
<sect1>Creating a database for MMBase<p>
MMbase needs a database and a user that has full rights on that database.
The user seems to needs rights via localhost and the real hostname.
This was not entirely clear to me.<p>
Issue the following commands on the MySQL prompt. I chose a database called MMBase, a user named mmbaseuser and
the password secret.<p>
<tscreen><verb>
CREATE DATABASE MMBase
USE MMBase
GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP ON MMBase.* TO mmbaseuser@'%' IDENTIFIED BY 'secret';
GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP ON MMBase.* TO mmbaseuser@localhost IDENTIFIED BY 'secret'
GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP ON MMBase.* TO mmbaseuser@realhostname IDENTIFIED BY 'secret'
flush privileges;
</verb></tscreen><p>
<sect1>Tomcat security manager<p>
The Tomcat java security manager somehow interferes with MMBase. I haven't
found out what settings are needed to run MMBase with the security manager
active. Please let me know. For now I disabled the security manager, which
you should never not do. (Big Disclaimer!)
In /etc/default/tomcat4 change the security line to:<newline>
TOMCAT4_SECURITY="no"
<sect1>Copying xml-apis<p>
For some odd reason, Tomcat wants to find the file WEB-INF/lib/xml-apis.jar also in
/usr/share/tomcat/common/lib/xml-apis.jar, so you have to copy it.<p>
<sect>Configuration files<p>
There are various configuration files that need some adjustment or have to be created.
<sect1>apache<p>
In my setup, I created a virtual host to handle all MMBase request, but using a few <em>Alias</em> directors
it cannot be too hard to include MMBase somewhere in your normal web tree.<p>
That was for my last setup (HOWTO version 0.1 covering MMBase 1.4).
Using the newest version of Tomcat and Apache, I have troubles getting the
two working together. As soon as I find out how to use libapache-mod-webapp
or libapache-mod-jk with tomcat4, I will update this HOWTO.<p>
One posible solution is compiling mod-webapp yourself, because the version
that comes with Debian seems to be non-standard. This is beyond the scope and intention of this
HOWTO.<p>
This also means that by default MMBase will run on port 8180 (directly from
the stand-alone Tomcat server. You can change this port in
/etc/tomcat4/server.xml
<sect1>MMBase<p>
Although many things have to be configured on MMBase itself, I have added a few subjects to this mini-HOWTO.<p>
The database access should be set in WEB-INF/config/modules/jdbc.xml :<p>
<tscreen><verb>
<property name="url">jdbc:mysql://$HOST:$PORT/$DBM?user=mmbaseuser&amp;password=secret&etago;/property>
<property name="user">url&etago;/property>
<property name="password">url&etago;/property>
<property name="database">MMBase&etago;/property>
<property name="driver">org.gjt.mm.mysql.Driver&etago;/property>
</verb></tscreen><p>
And one more line to change to get the mysql connection working. In WEB-INF/config/modules/mmbaseroot.xml
make sure you have this setting:
<tscreen><verb>
<property name="database">mysql&etago;/property>
</verb></tscreen><p>
The builder for images contains a path to convert that is not Debian-compliant. Change
WEB-INF/config/builders/images.xml
<tscreen><verb>
<properties>
<property name="ImageConvert.ConverterCommand">bin/convert&etago;property>
<property name="ImageConvert.ConverterRoot">/usr/&etago;property>
<property name="ImageConvertClass">org.mmbase.module.builders.ConvertImageMagick&etago;property>
&etago;properties>
</verb></tscreen><p>
<sect>Getting more help<p>
There are various sources for more help on most of the subject covered in this mini-HOWTO. All packages have
their own documentation. Some links that really helped me are:<p>
<itemize>
<item>Apache: <url name="http://httpd.apache.org/docs/" url="http://httpd.apache.org/docs/">
<item>Tomcat: <url name="http://jakarta.apache.org/tomcat/tomcat-4.0-doc/index.html" url="http://jakarta.apache.org/tomcat/tomcat-4.0-doc/index.html">
<item>MMBase: Click on Documentation on <url name="http://www.mmbase.org/" url="http://www.mmbase.org/">
<item>Java: <url name="http://java.sun.com/" url="http://java.sun.com/">
</itemize><p>
Another great source for help is channel #mmbase on ircnet, usually there are some developers there.
</article>

1151
LDP/retired/Oracle-8-HOWTO.sgml Normal file
View File

File diff suppressed because it is too large Load Diff

2430
LDP/retired/SCSI-Programming-HOWTO.sgml Normal file
View File

File diff suppressed because it is too large Load Diff

794
LDP/retired/Ultra-DMA.sgml Normal file
View File

@ -0,0 +1,794 @@
<!doctype linuxdoc system>
<!-- The Ultra-DMA Mini Howto SGML source
Version 3.01, 6/dec/2001
by Brion Vibber - brion@pobox.com
-->
<article>
<title>The Linux Ultra-DMA Mini-Howto
<author>Brion Vibber, <tt><htmlurl url="mailto:brion@pobox.com"
name="brion@pobox.com"></tt>
<date>v3.01, 6 December 2001
<abstract>
This document is intended to explain how to use Ultra-DMA aka Ultra-ATA
aka Ultra33 and Ultra66 hard drives and interfaces with Linux. The most
recent version of this mini-Howto can be obtained in HTML format at
<htmlurl url="http://pobox.com/~brion/linux/Ultra-DMA.html"
name="http://pobox.com/&tilde;brion/linux/Ultra-DMA.html">.
</abstract>
<toc>
<sect>Introduction and Disclaimer<label id="main-intro">
<p>
This document is intended to explain how to use Ultra-DMA aka Ultra-ATA
aka Ultra33 and Ultra66 hard drives and interfaces with Linux. In many cases there is
no difficulty in using them, but some tweaking can increase performance. In
other cases, you need to go to extraordinary lengths simply to access your
hard drives.
<sect1>Disclaimer<label id="disclaimer">
<p>
The information in this is document is, to the best of my knowledge, correct, and
should work. However, there may be typos, there may be mysterious
transmission errors, and there may be strange incompatibilities within your
own system that prevent the techniques described herein from working
properly. So... before you go fiddling around with you hard drive, <bf>BACK
UP ANY DATA YOU WANT TO KEEP!</bf> If you are not already performing regular
backups, please start doing so for your own good.
<sect1>Credits<label id="credits">
<p>
<url name="Michel Aubry" url="mailto:giovanni@sudfr.com"> - UDMA-enabled
VIA-related patch for &lt;=2.0.33
&amp; more info, grand unified UDMA patch for 2.0.34+
<url name="Andrew Balsa" url="mailto:andrebalsa@altern.org"> - Provided
some general UDMA info and the udma-generic patch for Intel TX, SiS, and VP1
on &lt;=2.0.33; also the grand unified UDMA patch for 2.0.34+
Maxime Baudin - French translation
Bokonon - ``Controller'' vs. ``interface''
<url name="John G." url="mailto:prefect@ipass.net"> -
VIA VP2 patch for &lt;=2.0.33 &amp; info
Martin Gaitan - Promise Ultra33 ide0/ide1 installation workaround
<url name="Andre M. Hedrick" url="mailto:andre@suse.com"> -
current Linux IDE subsystem maintainer
Håvard Tautra Knutsen - Norwegian translation
Norman Jacobowitz - Bugged me to add info on the VP3
John Levon - Info on TX Pro mobos
Peter Monta - Info on using two Ultra33 cards
Masayoshi Nakano - Japanese translation
<url name="Gadi Oxman" url="mailto:gadio@netvision.net.il"> - The
Promise Ultra33 patch for &lt;=2.0.34 &amp; finding the secret
numbers for the workaround
Andy Pearce - Suggested adding info on the additional device files for hde-h
<url name="Andrei Pitis" url="mailto:pink@roedu.net"> - LILO patch
<url name="Brion Vibber" url="mailto:brion@pobox.com"> - The document itself
<sect1>Document History<label id="history">
<p>
v3.01, 6 December 2001: Relicensed under <htmlurl
url="http://www.gnu.org/copyleft/fdl.html"
name="GNU Free Documentation License">; no content changes.
v3.0, 9 November 1999: Finally found time to update some key changes such as
the relocation of the IDE patch archive to the <url name="Kernel.org archives"
url="http://www.kernel.org/pub/linux/kernel/people/hedrick">... pesky school!
Updated all sunsite links to new <htmlurl url="ftp://metalab.unc.edu"
name="metalab.unc.edu"> or <htmlurl url="http://www.linuxdoc.org"
name="www.linuxdoc.org">
v2.1, 27 May 1999: Corrects some minor omissions and errors from 2.0 and adds
information on the Promise Ultra66 and 2.2/2.3 kernels.
v2.0, 7 August 1998: Major updates and almost total restructuring of the
document into onboard (motherboard) and offboard (add-in cards) interfaces;
the Grand Unified UDMA patch(a part of the Jumbo patch)
for 2.0.35. Put credits in alphabetical order by last name. Changed
``controller'' to ``interface'' in many cases to be more technically
correct. Added info on enabling/disabling UDMA, the blacklist, and more!
v1.45, 6 July 1998: Minor updates - Red Hat 5.1 and 2.0.34 patch for
Promise Ultra33, LILO patch for booting off of PCI interfaces such as
the Promise Ultra33
v1.41, 3 May 1998: Fixed a couple of typos, added translators to credits.
v1.4, 28 April 1998: UDMA-Generic patch, some more general info. Copying
section added.
v1.3, 5 March 1998: VIA VP3 info, better patching instructions,
pointer to more recent Promise patch.
v1.2, 27 January 1998: Additional Promise workaround info.
v1.1, 21 January 1998: New info about VIA chipset, installing <em/around/
the Promise Ultra33, and enabling Bus Master & UDMA transfer modes.
v1.0, 19 January 1998: More or less complete, first version done in SGML.
<sect1>Copying<label id="copying">
<p>
Copyright (c) 1998-2001 Brion L. Vibber
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with the Invariant Sections being &quot;Introduction and Disclaimer&quot;, with no
Front-Cover Texts, and with no Back-Cover Texts.
You should have received a copy of the GNU Free Documentation License
along with this document; if you did not, you may find it at
<htmlurl url="http://www.gnu.org/copyleft/fdl.html"
name="http://www.gnu.org/copyleft/fdl.html">.
<sect>What is Ultra-DMA and why do I want it?<label id="udma-intro">
<p>
Here's a brief overview of IDE-based drive technologies:
<sect1>IDE, EIDE, &amp; ATAPI<label id="classic">
<p>
These are older drive technologies. Most non-SCSI hard drives and drive
interfaces that you can buy today or are likely to be using are EIDE,
although many of the larger drives now available are UDMA.
<sect1>Bus Master DMA<label id="bm">
<p>
Bus Master DMA is a technology for increasing the speed of hard disk data
transfers which requires support from the motherboard and the BIOS, and at
least some support from the drive.
You can learn more at <htmlurl
url="http://developer.intel.com/design/pcisets/busmastr/FAQs.htm"
name="http://developer.intel.com/design/pcisets/busmastr/FAQs.htm">.
<sect1>Ultra-DMA aka Ultra-ATA aka Ultra33 aka...<label id="udma">
<p>
Ultra-DMA has many names, but we'll just call it UDMA in here.
UDMA is a more advanced technology which provides for even faster
throughput, up to 33.3 MB/s in UDMA mode 2 and 66.7 MB/s in UDMA mode 4,
twice to four times that of EIDE, for much lower prices
than SCSI. Many new computers come with large UDMA drives and UDMA
interfaces, and it's possible to add a UDMA interface card (such as
the Promise Ultra33 or Ultra66) to an existing system to boost speed, even on older
non-UDMA drives.
You can learn great details about UDMA at
<htmlurl url="http://www.quantum.com/src/whitepapers/ultraata/"
name="http://www.quantum.com/src/whitepapers/ultraata/">
Note that cable length should be kept shorter for UDMA, compared to plain DMA,
preferably less than 30 cm (12&quot;) maximum length though 18 inches will
usually be fine. 66 MB/s requires a special 80-conductor cable and should
definately not be longer. If you get a lot of CRC errors, try using a shorter
cable.
<sect1>Just how ``Ultra'' is it anyway?<label id="speed">
<p>
Before we get any farther, let's clear up a misconception. That 33 or 66 MB/sec
figure is the <bf/burst transfer rate/, and it's not something you're going to
see very often. To explain, here is a clip from udma­generic's UDMA.txt:
<tscreen><verb>
Burst (instantaneous) transfer rates are supposed to go from 16.6MB/s (PIO
mode 4) to 16.6MB/s (DMA mode 2) up to 33MB/s (UDMA). In his patch against
kernel 2.1.55, Kim-Hoe Pang actually checked the UDMA burst transfer rate
with a logic analiser: 60ns/word, which translates into 33MB/s.
Note that burst transfer rates only affect data transfers to/from the EIDE
drive cache (476kB for the IBM 6.4GB drive), and IMHO are not particularly
relevant for most Linux users.
The Linux kernel uses as much RAM as possible to cache hard disk data
accesses, and so if data is not in the kernel cache there is little chance
that it will be in the (much smaller) hard disk cache.
</verb></tscreen>
Much more relevant is the <bf/sustained transfer rate/, the speed at
which data can be transferred from the drive to main memory where it
can be used. An easy way to measure the sustained transfer rate is to
use <tt/hdparm/, for instance ``<tt>hdparm ­Tt /dev/hda</tt>'' to measure
the rate of the first IDE device.
<tscreen><verb>
Here is some data gathered after extensive testing, using the hdparm utility
(also written by Mark Lord):
PIO mode 4 transfer rates under Linux: +/- 5.2MB/s
DMA mode 2 transfer rates under Linux: +/- 7.2MB/s
UDMA mode 2 transfer rates under Linux: +/- 9.8MB/s
</verb></tscreen>
As you can see, UDMA is still almost twice as fast as plain EIDE and
significantly faster than plain bus mastering DMA. Most current UDMA drives
will give you between 10 and 15 MB/s using UDMA mode 2 (33 MB/s) or 4 (66 MB/s)
enabled.
Also, using DMA vastly reduces CPU usage during disk I/O vs PIO.
<sect1>How does UDMA compare to SCSI?<label id="udma-vs-scsi">
<p>
I don't have any hard numbers to give you, but the general consensus is that
high-end SCSI can give better performance than UDMA. However if you've looked
at the price tags on any hard drives lately you'll notice that UDMA drives
tend to be much less expensive. The performance/price ratio favors UDMA in
most cases.
<sect>Using your UDMA hard drive with an EIDE interface<label id="udma-on-eide">
<p>
This is easy to do. Since all UDMA drives are fully EIDE backward-compatible,
just plunk your drive on your EIDE interface like it was any old hard
drive and Linux should have no problems detecting or using it.
However, you will of course be limited to the slower speed of EIDE.
<sect>Using your hard drives with a UDMA interface<label id="using-udma">
<p>
Well, there is good news and there is bad news. The good news is that a UDMA
interface can be used with both UDMA hard drives and legacy EIDE hard
drives, and will be a lot faster than an EIDE interface.
The bad news is that the old stock kernels (2.0.x) do not currently
support UDMA very well. The new 2.2.x kernels do support UDMA33, however,
and kernel patches are available to add UDMA support for kernels that lack it.
In addition, certain UDMA interfaces that are add-in cards rather than built
into the motherboard require either a patch or some trickery to use on older kernels. That is why
this document exists - to explain how to get the patches and work the trickery.
<sect>Offboard PCI UDMA interfaces<label id="pci">
<p>
These are UDMA interfaces on PCI cards that can be used to add UDMA
support to an existing computer without replacing the motherboard, or
for adding support for an additional four drives to a machine which has
had its onboard interfaces filled. They can also be found preinstalled
in some computers, especially Gateway 2000 and Dell machines.
Most of them are not supported by the old stable kernels (2.0.x), but many should
work with a 2.2.x kernel - the Red Hat 6.0 and SuSE 6.1 distributions are
based on 2.2.x kernels, as are the most recent versions of most other distros.
However some of the latest cards (the Promise Ultra66 for instance) won't
work even with the current 2.2.x kernels, if you have this or can't get a
newer distribution then you must apply a kernel patch or upgrade to a newer
kernel version.
If you need to install Linux onto a hard drive on one of these interfaces
in this case, you will need to use a few odd tricks.
<sect1>Promise Ultra33<label id="promise">
<p>
This is a PCI card that has two UDMA channels on it, supporting up to four
drives total. You can look up specifications &amp; pricing at
<htmlurl url="http://www.promise.com" name="http://www.promise.com">.
This card shipped in early model Gateway 2000 Pentium II systems.
Kernels 2.0.35 and later and all 2.2.x kernels support the Ultra33 and
you should have no trouble installing a distribution that uses these kernels.
However, the older stable kernels (2.0.34 and below) do not, and
since most older Linux distributions include these older kernels it can
be a little difficult to get Linux installed if you can't or don't want
to use a newer version (for instance if you are standardized on a particular
version of a distribution throughout your organization).
<bf/Installing Linux with the Ultra33/
Although there is a patch for the Ultra33 interface,
it is not very easy to apply a patch and recompile your kernel if you have
not installed Linux yet! So, here is a workaround which allows you to
install. Thanks to Gadi Oxman for the following information on getting the
interface settings:
<tscreen><verb>
If we can access the console with the installation disk, we can also
use "cat /proc/pci" to display the Promise interface settings:
RAID bus interface: Promise Technology Unknown device (rev 1).
Vendor id=105a. Device id=4d33.
Medium devsel. IRQ 12. Master Capable. Latency=32.
I/O at 0xe000. (a)
I/O at 0xd804. (b)
I/O at 0xd400. (c)
I/O at 0xd004. (d)
I/O at 0xc800. (e)
and pass "ide2=a,b+2 ide3=c,d+2" as a command line parameter to the kernel.
</verb></tscreen>
Note that the numbers probably are not the same as what you will have.
Just as an example, the parameters to use for the above set of numbers
would be ``<tt/ide2=0xe000,0xd806 ide3=0xd400,0xd006/''.
If you are only using the first channel on the Ultra33 (for
instance, if you only have one drive, or two if they are master and slave on
the same channel), then you won't need to specify <tt/ide3/.
<bf/Red Hat 5.1:/ Boot with the boot diskette and press enter when prompted.
The kernel will load, and then you will be asked for a language, keyboard
type, and installation method. You may be prompted for additional information
about the source media; it doesn't matter right now what you tell it as long
as you can get to the next step. Next you should see a screen titled
``Select Installation Path''; press Alt-F2 now to get to a command prompt.
Run ``<tt>cat /proc/pci</tt>'', write down
the numbers as above, and reboot from the boot disk. This time, type
``<tt>linux ide2=</tt> <em/(this is where you put the numbers like shown
above)/<tt/ ide3=/<em/(more numbers)/''. It should now be able to install
onto your hard disk without difficulty, however LILO will probably not be able to
install; instead make a boot floppy and boot it with the same parameters
until you can patch LILO and and the kernel.
<bf/Red Hat 5.0/ and <bf/Slackware 3.4:/ These are similar, but with the wrinkle
that the setup programs ignore <tt>/dev/hde-h</tt> (the drives on <tt/ide2/ and <tt/ide3/).
In order to install to or from these drives it is necessary to override one or
both of the onboard interface's channels. However be sure not to override a
device that you need to install; for instance if you are installing from a CD-ROM drive on
<tt>/dev/hdd</tt> (<tt/ide1/ - onboard interface) to a hard drive on <tt>/dev/hde</tt>
(<tt/ide2/ - the Ultra33), you should override the non-essential <tt/ide0/ with
<tt/ide2/ and leave <tt/ide1/ intact. Assuming the numbers above you would boot with
``<tt/ide0=0xe000,0xd806/''. Red Hat 5.0 will give you a shell prompt if you use
the rescue disk capability, and Slackware includes a shell in the regular installation
process. However Red Hat 5.0 is difficult to boot after installation; if you have
problems you could try downloading a Slackware boot disk from <htmlurl
url="ftp://ftp.cdrom.com/pub/linux/slackware-3.5/bootdsks.144/"
name="ftp://ftp.cdrom.com/pub/linux/slackware-3.5/bootdsks.144/">
and using that to boot.
With another Linux distribution you will have to improvise a bit, but the
process should be about the same as the above.
<bf><em>IMPORTANT:</em></bf> Without the patch (discussed in the
section <ref id="unified" name="Unified IDE">), the
kernel <bf>needs</bf> these boot parameters in order to access your hard
disk! Therefore it is very important that when you configure LILO, either on
the hard disk or on a boot floppy, that you give it the <bf>exact same
parameters</bf> that you gave when installing. Otherwise your system won't
boot! It should be possible to give them to LILO when you boot (ie, press
Shift, type in ``<tt/linux ide2=/<em/...../'' each time you boot), but only
if you kept the numbers! It is recommended that you patch your kernel as soon
as possible so you will not have to worry about that anymore; once you are
booting with a patched kernel, you can get rid of the boot parameters. Also,
as far as I know there is no way to pass boot parameters to a plain kernel
boot floppy (as made with ``<tt/make zdisk/''), you <bf>must</bf> use LILO or
another loader (such as LOADLIN) that lets you pass boot parameters.
However, unpatched kernels and installation programs often have a difficult
time actually using ide2 and ide3, even if the drives are detected properly.
So if you can't get Linux to install using the above technique, try
specifying ide0 or ide1 instead of ide2 or ide3 (thanks to Martin Gaitan for
this technique). This essentially replaces the on-board interface
with the Promise Ultra33 as far as the kernel is concerned, and you can
follow the directions in the next section as if you had physically moved it.
Note that if you're using an IDE CD-ROM drive connected to your on-board
interface to install from, you will want to make sure that you do not take
over the interface that the CD is on or you will not be able to install! If
the CD is hda or hdb, use ide1 for your hard drive, and if it is hdc or hdd,
then use ide0.
<bf/Installing Linux Around the Ultra33/
If you cannot get the software workaround to work, you will have to try a
more brute force approach. Here's an alternative method that is virtually
guaranteed to work, but will require you to open up your computer and mess
about in it. <bf/NOTE:/ If you are not familiar with the process of
connecting and disconnecting IDE drives, <bf/read the manuals/ that came
with your computer, your hard drive, and/or the Promise Ultra33 before
attempting this! If you screw something up and don't know how to put it
back, you could end up being sorry!
That being said, it's all really quite simple. Most motherboards these days
have built-in EIDE interfaces. Disconnect your hard drive from the Ultra33
and connect it to the onboard interface. If you have other IDE devices,
such as a CD-ROM, tape, or ZIP drive, on your oboard interface, it is
easiest if you either add the hard drive on an unused channel (the secondary
instead of the primary) or temporarily displace a device that you don not
need immediately (such as ZIP or tape). Install Linux. Download and apply
the Promise UDMA patch (see next section).
Now you are ready to move the drive back onto the Promise... almost. To be
safe, make a kernel-image boot floppy (<tt>cd /usr/src/linux ; make
zdisk</tt>), which you will be able to use to boot your system in case LILO
doesn't work. Actually, to be <em/very/ safe, make two and put one away for
now.
Okay, now it is time
to think a little... if you have just one hard drive and it is going to be on
the Promise, then it will most likely be <tt>/dev/hde</tt> (<tt/a/ and
<tt/b/ are for the primary
onboard interface, <tt/c/ and <tt/d/ for the secondary onboard interface).
If you are going to put any other drives on it, then the slave of the
Promise's first channel will be <tt>/dev/hdf</tt>, the master of the second
will be <tt>/dev/hdg</tt>, and the slave of the second will be
<tt>/dev/hdh</tt>.
Edit <tt>/etc/fstab</tt>, and change all the partitions of the hard drives
you are moving from the onboard drives (<tt>/dev/hda</tt>, <tt>hdb</tt>,
etc) to their new locations on the Promise (<tt>/dev/hde</tt>, <tt>hdf</tt>,
etc). If you had to displace any devices (such as a CD-ROM or ZIP drive)
that you want to leave on the onboard interface, then change them to their
new locations as well. For instance, if your CD-ROM was originally the
master on the primary channel (<tt>/dev/hda</tt>), but you put your hard disk
there and had to bump the CD to the slave (<tt>/dev/hdb</tt>) or to the
secondary channel (<tt>/dev/hdc</tt>), and now you want to put it back, then
change it to <tt>/dev/hda</tt>.
If you are using LILO, reconfigure LILO to use the new location of the drive
(LILO configuration is beyond the scope of this document, if you do not know
how, read the <url url="http://www.linuxdoc.org/HOWTO/mini/LILO.html"
name="LILO mini-HOWTO">),
or else it probably will not be able to boot unless you use that boot floppy
I had you make, which you will also want to configure to boot off the new
partition. This is done using the <tt/rdev/ command. Put the floppy in the
drive and type ``<tt>rdev /dev/fd0 /dev/hde1</tt>''. Of course that's assuming
your root partition is the first on your first UDMA drive. If not (mine is
<tt>/dev/hde7</tt>, for instance), then obviously use the appropriate
partition number!
Reboot. Your system should now work fine.
<bf/Patching for the Ultra33/
Kernels 2.0.35 and later support the Promise Ultra33 natively; download an upgrade
from your Linux distribution or from <htmlurl name="http://www.kernel.org"
url="http://www.kernel.org">.
For instructions on how to compile the kernel, read the <htmlurl name="Kernel HOWTO"
url="http://www.linuxdoc.org/HOWTO/Kernel­HOWTO.html">.
<bf/Using two Ultra33 cards in one machine/
This is currently not working correctly... don't do it right now unless you're
willing to fiddle with the kernel to try to get things to work.
<sect1>Promise Ultra66<label id="promise66">
<p>
This is essentially the same as the Ultra33 with support for the new UDMA mode 4
66 MB/sec transfer speed. Unfortunately it is not yet supported by 2.2.x
kernels.
There is a patch for 2.0.x and 2.2.x kernels availabe at
<htmlurl url="http://www.kernel.org/pub/linux/kernel/people/hedrick"
name="http://www.kernel.org/pub/linux/kernel/people/hedrick">, and support is
included in the 2.3.x development kernel series at least as of 2.3.3.
However to get far enough to patch or upgrade the kernel you'll have to pull
the same dirty tricks as for the Ultra33 as in the section above, or else
use a boot disk image <url name="provided by Promise"
url="http://www.promise.com/latest/latedrivers.htm#linuxu66">
<sect1>Artop ATP850UF<label id="artop">
<p>
This card is supported by the unified IDE code. Installation of Linux onto a system
with one of these as the interface for the target disk may be similar to the
workarounds for the Promise Ultra33.
<sect1>Adding device files
<p>
The tertiary and quaternary IDE interfaces (ide2 and ide3) use device files of
the form <tt>/dev/hde*</tt> through <tt>/dev/hdh*</tt>. On older kernels these
devices were not automatically created, so you may need to add them manually
for things to work properly.
This can be done easily if you have a current copy of the Linux kernel source
installed; simply run <tt>/usr/src/linux/scripts/MAKEDEV.ide</tt> and it will create
all relevant device files.
<sect>Onboard UDMA interfaces<label id="onboard">
<p>
These are UDMA­capable drive interfaces built into motherboards. They use
the standard IDE I/O ports and so are fully usable at the slower non­UDMA
speeds on an unpatched 2.0.x kernel such as are used when installing Linux.
Thus they should not cause any difficulties during installation, and patching
for UDMA speed is a welcome luxury instead of a necessary step. Some UDMA
support is in the latest 2.0.x kernels I believe, and is built into current
2.2.x kernels for the Intel chipsets.
<sect1>Intel FX, HX, VX, TX, LX, and BX<label id="intel">
<p>
Thanks again to Gadi for this info:
<tscreen><verb>
Bus mastering DMA support for the Intel TX chipset is available in 2.0.31
and above.
</verb></tscreen>
In older kernels (such as Slackware 3.4's 2.0.30), the interface will be
used in the slower EIDE mode.
In either case the interface will be automatically detected by the kernel
and you should have no trouble using it.
Full UDMA mode 2 support for these chipsets is included in 2.2.x kernels
and the unified IDE patch; see <ref id="unified" name="Unified IDE">.
<sect1>The VIA VP2 and Related Chipsets<label id="via">
<p>
This interface also can be autodetected and used in EIDE mode by an unpatched
kernel, but if you have one of these, you will want to grab a patch so you
can get faster throughput and do away with annoying "unkown PCI device"
messages.
One is available at
<htmlurl url="http://www.ipass.net/~prefect"
name="http://www.ipass.net/&tilde;prefect/">; it is designed for the VIA VP2/97
chipset, found on FIC's PA-2007 and PA-2011 motherboards, but may work on related chipsets.
It has been reported that it functions on the newer VIA VP3 chipset, your mileage may vary.
Note that this patch only supports Bus Mastering mode,
not full UDMA mode, but it's still better than plain-vanilla EIDE mode.
Follow the directions at the patch's site for enabling BMDMA mode.
There is another patch that supports full UDMA mode at
<htmlurl url="http://www.pyreneesweb.com/Udma/udma.html"
name="http://www.pyreneesweb.com/Udma/udma.html">,
designed for the VIA VT82C586B, and it ought to work on the
VP2, VP3, VPX, P6 and AGP Apollo chipsets. Follow the directions
for installation and UDMA enabling there, but it is recommended that you
back up any data you want to keep, as there are potential problems with
incompatible motherboards. But, if it does work, it should work without
problems.
Note that the VP1 chipset is not known to work with these patches,
but is supported by the <ref id="unified" name="Unified IDE"> patch.
<sect1>TX Pro and other ``Pro'' boards
<p>
UDMA is not currently supported for the TX Pro motherboards. They are not
the same as a TX mobo, and apparently misreport their DMA capabilities hence
the problem. Someone is working on this I hear, so a patch may appear some
time in the future but not yet.
<sect1>HPT 366<label id="hpt366">
<p>
This chipset is on the popular Abit BP-6 motherboard and others, and provides
UDMA mode 4 66MB/s support on two generals, generally in addition to two
other mode 2 33MB/s channels. It is supported by the current <ref id="unified"
name="unified IDE code"> but not in any current release kernels. Installation
thus may require workarounds similar to the <ref id="promise"
name="Promise Ultra33"> did on older 2.0.x kernels.
<sect>Unified IDE Patches<label id="unified">
<p>
The unified IDE patches provide support for many chipsets and offboard cards,
and are available for 2.0.x, 2.2.x, and the 2.3.x development kernels. If your
chipset isn't supported by a current stock kernel, you'll want to patch it with
these.
The unified IDE code is maintained by <url name="Andre Hedrick" url="mailto:andre@suse.com">,
and patches are available at <url name="your local kernel archive mirror"
url="http://www.kernel.org/pub/linux/kernel/people/hedrick">.
UDMA support is provided for at least the following chipsets, and probably
many more I don't know about:
<itemize>
<item>All Intel chipsets: FX, HX, VX, TX, LX
<item>All SiS chipsets (only SiS5598 tested, but this entire family of
chipsets has the same bult-in 5513 interface device).
<item>VIA chipsets (only 82C586B tested, but again this family of
chipsets has the same interface structure). Special diagnostics
support is available for the VIA interfaces.
<item>Promise and Artop PCI UDMA interface cards support.
<item>Aladdin V (ALi15x3) chipset
<item>HPT343 board and HPT366 onboard chipset (caveat, see <ref id="hpt366" name="Abit BP-6">)
</itemize>
It is also designed to be easy to extend to support other chipsets.
Here are a few notes from Andre Balsa, the author of an earlier patch:
<tscreen><verb>
Performance with IBM UDMA drives on a good motherboard approches the
maximum head transfer rates: about 10 Mb/s (measured with hdparm -t -T).
The Intel TX chipset has a single FIFO for hard disk data shared by
its two IDE interfaces, so using 2 UDMA drives will not yield such a
great improvement over a single UDMA drive.
However, the SiS5598 has two completely separate interfaces, each with
its own FIFO. Theoretically, one could approach 66Mb/s burt transfer
rates on motherboards with the SiS5598 chip, using the md driver and
data striping over two drives. The SiS5571 has the same interface
architecture, I think. I don't have the VIA chipsets datasheets, so I
can't say anything about those.
The Linux IDE (U)DMA kernel driver by Mark Lord has a particularly
low setup time (i.e. latency for data transfers). It is ideal for
frequent, small data transfers (such as those in Linux news servers),
and might be in some cases superior to its SCSI counterparts.
</verb></tscreen>
<sect>Activating and Deactivating UDMA<label id="activate">
<p>
Normally, a UDMA-aware kernel will automatically enable UDMA support for
drives and interfaces that support it. In most cases that it doesn't, the kernel
either doesn't know how to drive your IDE chipset (get yourself a patch, see
<ref id="unified" name="above">) or doesn't believe it is safe to enable
it (meaning you shouldn't!).
However in some cases the drive is capable of UDMA but the BIOS drops the ball
and doesn't report it properly, and forcing the issue can be useful.
<sect1>Using kernel boot parameters<label id="bootparam">
<p>
On kernels 2.1.113 and up, you can enable DMA for both drives on a given IDE
interface using the <tt/ideX=dma/ kernel parameter, where X is the number
of the interface (the first is 0). This may not actually force UDMA though.
Kernel boot parameters can be set using LILO, LOADLIN, or most Linux boot
loaders. For more information see the <htmlurl name="Bootdisk HOWTO"
url="http://www.linuxdoc.org/HOWTO/Bootdisk-HOWTO.html">.
<sect1>Using hdparm<label id="hdparm">
<p>
<tt/hdparm/ is a program used to tweak the parameters of hard drives under
Linux. Among other things you can use it to enable or disable UDMA for a
drive and test its sustained transfer rate.
The current version of <tt/hdparm/, is 3.6 as of this writing. Unpatched older versions
will not properly report or set information on UDMA, so be sure to upgrade! You
can obtain the source code for hdparm 3.6 at
<htmlurl url="http://metalab.unc.edu/pub/Linux/system/hardware/hdparm-3.6.tar.gz"
name="http://metalab.unc.edu/pub/Linux/system/hardware/hdparm-3.6.tar.gz">.
Compile and install it something like this:
<tscreen><verb>
tar zxvf /tmp/download/hdparm-3.6.tar.gz
cd hdparm-3.5
make
su root
(type password when prompted)
make install
cp /usr/local/sbin/hdparm /sbin/hdparm
exit
</verb></tscreen>
<bf/To enable DMA for a hard drive:/ <tt>hdparm -d1 /dev/hda</tt>
<bf/To disable DMA for a hard drive:/ <tt>hdparm -d0 /dev/hda</tt>
<bf/To measure transfer rate of a hard drive:/ <tt>hdparm -Tt /dev/hda</tt>
<bf/To see what options are enabled for a hard drive:/ <tt>hdparm /dev/hda</tt>
<bf/To see more info on your drive than you wanted to know/: (this will show which UDMA
modes are supported/enabled)
<tt>hdparm -i /dev/hda</tt>
For more detailed info (such as how to choose which UDMA mode to use) read
the man page (``<tt/man 8 hdparm/'').
<sect>Problems
<sect1>The UDMA Blacklist<label id="blacklist">
<p>
The following drives are ``blacklisted''. You should <bf/not/ use UDMA with
these drives as it may cause corruption of data. To avoid this, the driver
should automatically disable DMA for these drives.
<itemize>
<item>Western Digital WDC AC11000H, AC22100H, AC32500H, AC33100H, AC31600H - all versions
<item>Western Digital WDC AC32100H revision 24.09P07
<item>Western Digital WDC AC23200L revision 21.10N21
</itemize>
<sect1>Are you overclocking?
<p>
If you are, beware! Here is a quote from the old udma-generic documentation:
<tscreen><verb>
DON'T OVERCLOCK the PCI bus. 37.5MHz is the maximum supported speed for
the PCI bus. Some (supposedly compatible) UDMA drives will not even take
37.5MHz, but should be OK at 33.3MHz.
In any case, NEVER, NEVER set the PCI bus to 41.5MHz.
The RECOMMENDED safe setting is 33MHz.
</verb></tscreen>
<sect1>Is your BIOS current?
<p>
Here is another clip from the udma-generic docs:
<tscreen><verb>
The real work involved in setting up the chips for DMA transfers is done
mostly by the BIOS of each motherboard. Now of course one hopes that the
BIOS has been correctly programmed...
For example, the ASUS SP-97V motherboard with its original BIOS (Rev. 1.03)
would malfunction with the modified Linux driver in both DMA mode 2 and UDMA
modes; it would work well using PIO mode 4, or under Windows 95 in all
modes. I downloaded the latest BIOS image (Rev. 1.06) from the ASUS Web site
and flashed the BIOS EPROM with the latest BIOS revision. It has been
working perfectly ever since (at 66 MHz bus speeds).
What this tells us is that the BIOS sets up the DMA controller with specific
timing parameters (active pulse and recovery clock cycles). My initial BIOS
revision probably had bad timings. Since the Windows 95 driver sets up those
timings by itself (i.e. it does not depend on the BIOS to setup the hard
disk controller timing parameters), I initially had problems only with the
Linux driver, while Windows 95 worked well.
So, let me state this again: this Linux (U)DMA driver depends on the BIOS for
correct (U)DMA controller setup. If you have problems, first check that you
have the latest BIOS revision for your specific motherboard.
...
New BIOS revisions can be downloaded from your motherboard manufacturer's
Web site. Flashing a new BIOS image is a simple operation but one must
strictly follow the steps explained on the motherboard manual.
Late Award BIOS revisions seem stable with respect to UDMA. Anything with a
date of 1998 should be fine.
</verb></tscreen>
<sect1>If you still can't get it to work!<label id="help">
<p>
If nothing in this document proved helpful, or at least not helpful enough
to get your machine working, your best bet is to write up a message that
fully describes your difficulty, what type of UDMA interface you have,
whether it is onboard or on a card, if your drive is actually UDMA or plain
EIDE, exactly what configuration of drives you have, what version (distribution
&amp; kernel versions if possible) of Linux you are using, and anything
else that sounds useful, and post it to the newsgroup
<htmlurl url="news:comp.os.linux.hardware" name="comp.os.linux.hardware">.
You will probably get some helpful suggestions soon.
<sect>If you have some information about UDMA stuff that's not in this mini-howto...
<label id="suggest">
<p>
Great! If you know something I don't, by all means send it to me
(<htmlurl url="mailto:brion@pobox.com" name="brion@pobox.com">)
and I will put it in this document and update it fairly soon.
</article>

360
LDP/retired/VPN.sgml Normal file
View File

@ -0,0 +1,360 @@
<!doctype linuxdoc system>
<article>
<title>The VPN HOWTO
<author>Arpad Magosanyi &lt;mag@bunuel.tii.matav.hu&gt; v0.2,7 Aug1997
<date>v0.3, 2001-12-01
<p>
<bf>Archived Document Notice:</bf> This document has been archived by the LDP
because it does not apply to modern Linux systems. It is no longer
being actively maintained.
</p>
<sect>Changes
<p>
The 'no controlling tty problem' -&gt; -o 'BatchMode yes' by Zot O'Connor &lt;zot@crl.com&gt;
warning about kernel 2.0.30 by mag
<sect>Blurb
<p>
This is the Linux VPN howto, a collection of information on how to set up a Virtual Protected Network in Linux (and other unices in general).
<sect1>Copyright
<p>
This document is part of the Linux Documentation Project. The copyright notice is the following:
<p>
The VPN mini HOWTO written by me can be copied,
distributed, and/or modified under the terms of the GNU Free Documentation
License, Version 1.1 or any later version published by the Free Software
Foundation; with the Invariant Section being the section entitled "About
the ppp over ssh vpn technique", with any Front-Cover Text containing the p=
hrase
"Based on the work of Arpad Magosanyi", and with any Back-Cover Text.
<sect1>Disclaimer
<p>
As usual: the author not responsible for any damage. For the correct wording, see the relevant part of the GNU GPL 0.1.1
<sect1>Disclaimer
<p>
We are dealing with security: you are not safe if you haven't got good security policy, and other rather boring things.
<sect1>Credits
<p>
Thanks to all of who has written the tools used.
Thanks to Zot O'Connor &lt;zot@crl.com&gt; for pointing out the "no controlling tty" problem, and it's solution.
<sect1>State of this document
<p>
This is very preliminary. You should have thorough knowledge of administrating IP, at least some knowledge of firewalls, ppp and ssh. You should know them anyway if you want to set up a VPN. I just decided to write down my experiences not to forget them. There are possibly some security holes indeed. To be fair I've tried it on hosts configured as routers not firewalls, saying: It's simple from that point.
<sect1>Related documentations
<p>
<itemize>
<item>The Linux Firewall-HOWTO /usr/doc/HOWTO/Firewall-HOWTO
<item>The Linux PPP-HOWTO /usr/doc/HOWTO/PPP-HOWTO.gz
<item>The ssh documentations /usr/doc/ssh/*
<item>The Linux Network Admins' Guide
<item>NIST Computer Security Special Publications http://csrc.ncsl.nist.gov/nistpubs/
<item>Firewall list (majordomo@greatcircle.com)
</itemize>
<sect>Introduction
<p>
As firewalls are in more and more widely use in internet and intranet security, the ability to do nice VPNs is important. Here are my experiences. Comments are welcome.
<sect1>Naming conventions
<p>
I will use the terms "master firewall" and "slave firewall", though making a VPN has nothing to do with client-server architecture. I simply refer to them as the active and passive participants of the connection's setup. The host which is starts the setup will be referred as the master, and the passive participant will be the slave.
<sect>Doing it
<p>
<sect1>Planning
<p>
Before you start to set up your system, you should know the networking details. I assume you have two firewalls protecting one intranet per firewall, and they are both connected to the internet. So now you should have two network interfaces (at least) per firewall. Take a sheet of paper, write down their IP addresses and network mask. You will need one more IP adresses per firewall for the VPN you want to do now. Those addresses should be outside of your existing subnets. I suggest using addresses from the "private" address ranges. They are the followings:
<itemize>
<item>10.0.0.0 - 10.255.255.255
<item>172.16.0.0 - 172.31.255.255
<item>192.168.0.0 - 192.168.255.255
</itemize>
For the sake of example, here's a sample configuration: The two bastions are called fellini and polanski. They have one interface for the internet (-out), one for the intranet (-in), and one for the vpn (-vpn). The addresses and netmasks:
<itemize>
<item>fellini-out: 193.6.34.12 255.255.255.0
<item>fellini-in: 193.6.35.12 255.255.255.0
<item>fellini-vpn: 192.168.0.1 point-to-point
<item>polanski-out: 193.6.36.12 255.255.255.0
<item>polanski-in: 193.6.37.12 255.255.255.0
<item>polanski-vpn: 192.168.0.2 point-to-point
</itemize>
So we have the plan.
<sect1>Gathering the tools
<p>
You will need a
<itemize>
<item>Linux firewall
<item>kernel
<item>very minimal configuration
<item>ipfwadm
<item>fwtk
<item>Tools for the VPN
<item>ssh
<item>pppd
<item>sudo
<item>pty-redir
</itemize>
Current versions:
<itemize>
<item>kernel: 2.0.29 Use a stable kernel, and it must be newer than 2.0.20, because the ping'o'death bug. At the time of writing 2.0.30 is the last "stable" kernel, but it has some bugs. If you want to have the fast and cool networking code introduced in it, try a prepatch. the 3rd is working for me nicely.
<item>base system: I prefer Debian. YMMV. You absolutely don't want to use any big packages, and you never even tought of using sendmail, of course. You also definitely don't want to enable telnet, ftp, and the 'r' commands (as usual in case of any other unix hosts).
<item>ipfwadm: I've used 2.3.0
<item>fwtk: I've used 1.3
<item>ssh: &gt;= 1.2.20. There are problems with the underlying protocol in the older versions.
<item>pppd: I've used 2.2.0f for the tests, but I'm not sure if is it secure, this is why I turned the setuid bit off, and used sudo to launch it.
<item>sudo: 1.5.2 the newest I am aware of
<item>pty-redir: It is written by me. Try ftp://ftp.vein.hu/ssa/contrib/mag/pty-redir-0.1.tar.gz. Its version number is 0.1 now. Tell me it there is any problem with it.
</itemize>
<sect1>Compile and install
<p>
Compile or otherwise install the gathered tools. Look at every one's documentation (and the firewall-howto) for details. Now we have the tools.
<sect1>Configure the other subsystems
<p>
Configure your firewall rules, etc. You need to enable ssh traffic between the two firewll hosts. It means a connection to port 22 on the slave from the master. Start sshd on the slave and verify if you can login. This step is untested, please tell me your results.
<sect1>Set up the accounts for the VPN
<p>
Create an account on the slave firewall use your favourite tool (e.g. vi, mkdir, chown, chmod) you might create an account on the master also, but I think you want to set up the connection at boot time, so your ordinary root account will do. Can anyone point out risks on using the root account on the master?
<sect1>Generate an ssh key for your master account
<p>
Use the ssh-keygen program. Set empty password for the private key if you want to do automatic setup of the VPN.
<sect1>Set up automatic ssh login for the slave account
<p>
Copy the newly generated public key in the slave account under .ssh/authorized_keys, and set up file permissions like the following:
<verb>
drwx------ 2 slave slave 1024 Apr 7 23:49 ./
drwx------ 4 slave slave 1024 Apr 24 14:05 ../
-rwx------ 1 slave slave 328 Apr 7 03:04 authorized_keys
-rw------- 1 slave slave 660 Apr 14 15:23 known_hosts
-rw------- 1 slave slave 512 Apr 21 10:03 random_seed
</verb>
The first row being &tilde;slave/.ssh, and the second is &tilde;slave.
<sect1>Tighten ssh security on the bastions.
<p>
It means the followings on my setup in sshd_conf:
<verb>
PermitRootLogin no
IgnoreRhosts yes
StrictModes yes
QuietMode no
FascistLogging yes
KeepAlive yes
RhostsAuthentication no
RhostsRSAAuthentication no
RSAAuthentication yes
PasswordAuthentication no
PermitEmptyPasswords no
</verb>
Password authentication is turned off, so login is only possible with authorized keys. (You've turned off telnet and the 'r' commands of course).
<sect1>Enable execution of ppp and route for both accounts.
<p>
As the master account is the root in my case, it has nothing to do. For the slave account, the following lines appear in /etc/sudoers:
<verb>
Cmnd_Alias VPN=/usr/sbin/pppd,/usr/local/vpn/route
slave ALL=NOPASSWD: VPN
</verb>
As you can see, I am using some scripts to set up ppp and the routing tables on the slave host.
<sect1>Do the scripting
<p>
On the master host there is a full-blown init script I am using:
<verb>
#! /bin/sh
# skeleton example file to build /etc/init.d/ scripts.
# This file should be used to construct scripts for /etc/init.d.
#
# Written by Miquel van Smoorenburg <miquels@cistron.nl>.
# Modified for Debian GNU/Linux
# by Ian Murdock <imurdock@gnu.ai.mit.edu>.
#
# Version: @(#)skeleton 1.6 11-Nov-1996 miquels@cistron.nl
#
PATH=/usr/local/sbin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/bin/X11/:
PPPAPP=/home/slave/ppp
ROUTEAPP=/home/slave/route
PPPD=/usr/sbin/pppd
NAME=VPN
REDIR=/usr/local/bin/pty-redir
SSH=/usr/bin/ssh
MYPPPIP=192.168.0.1
TARGETIP=192.168.0.2
TARGETNET=193.6.37.0
MYNET=193.6.35.0
SLAVEWALL=polanski-out
SLAVEACC=slave
test -f $PPPD || exit 0
set -e
case "$1" in
start)
echo setting up vpn
$REDIR $SSH -o 'Batchmode yes' -t -l $SLAVEACC $SLAVEWALL sudo $PPPAPP >/tmp/device
TTYNAME=`cat /tmp/device`
echo tty is $TTYNAME
sleep 10s
if [ ! -z $TTYNAME ]
then
$PPPD $TTYNAME ${MYPPPIP}:${TARGETIP}
else
echo FAILED!
logger "vpn setup failed"
fi
sleep 5s
route add -net $TARGETNET gw $TARGETIP
$SSH -o 'Batchmode yes' -l $SLAVEACC $SLAVEWALL sudo $ROUTEAPP
;;
stop)
ps -ax | grep "ssh -t -l $SLAVEACC " | grep -v grep | awk '{print $1}' | xargs kill
;;
*)
# echo "Usage: /etc/init.d/$NAME {start|stop|reload}"
echo "Usage: /etc/init.d/$NAME {start|stop}"
exit 1
;;
esac
exit 0
</verb>
The slave uses one script for routing setup (/usr/local/vpn/route):
<verb>
#!/bin/bash
/sbin/route add -net 193.6.35.0 gw 192.168.0.1
</verb>
and its .ppprc consists of the following:
<verb>
passive
</verb>
<sect>Look at what's happening:
<p>
The master logs in into the slave, starts pppd, and redirects this all thing into a local pty. It consists of the following steps:
<itemize>
<item>allocating a new pty
<item>sshing into the slave
<item>running pppd on the slave
<item>the master runs pppd in this local pty
<item>and sets up the routing table on the client.
</itemize>
There are (not very tight) timing considerations involved, this is why that 'sleep 10s'.
<sect>Doing it by hand.
<p>
<sect1>Logging in
<p>
You've already tried if ssh works well, aren't you? If the slave refuses to log you in, read the logs. Perhaps there are problems with file permissions or the sshd setup.
<sect1>Firing up ppp
<p>
Log in into slave, and issue:
<verb>sudo /usr/sbin/pppd passive
</verb>
You should see garbage coming at this point. If it works good, if not, there is some problem either with sudo, either with pppd. Look what the commands had said, and at the logs and at the <em>/etc/ppp/options</em>, and the <em>.ppprc </em>file. If it works, write this 'passive' word into .ppprc, and try again. To get rid off the garbage and continue working, press enter,'&tilde;' and '^Z'. You should have the master's prompt now, and kill &percnt;1. See the section about tuning if you want to know more of the escape character.
<sect1>Together the two
<p>
Well, then
<verb>ssh -l slave polanski sudo /usr/sbin/pppd
</verb>
should work also, and deliver the garbage right into your face.
<sect1>Pty redirecting
<p>
Try to redirect this whole thing this time:
<verb>/usr/local/bin/pty-redir /usr/bin/ssh -l slave polanski sudo /usr/sbin/pppd
</verb>
Nice long sentence isn't it? You should use the full path into the ssh executable, as the pty-redir program allows only this form for security reasons. Now you've got a device name from the program. Let's say, you've got <em>/dev/ttyp0 </em> You can use the ps command to look what has happened. Look for 'p0'
<sect1>Is anything on the device?
<p>
Try
<verb>/usr/sbin/pppd /dev/ttyp0 local 192.168.0.1:192.168.0.2
</verb>
to establish the connection. Look at the output of the ifconfig command to see if the device has established, and use ping to check your virtual net.
<sect1>Setting up the routes
<p>
Set up the routes on the master host, and on the slave also. Now you should be able to ping one host in one intranet from other host in the other intranet. Set up the additional firewalling rules. Now as you have the VPN, you can set up the rules concerning the connectivity of the two intranets.
<sect>Tuning
<p>
<sect1>Configuration tuning
<p>
As I said this HOWTO is mainly a quick memo on how I had set up a VPN. There are things in the configuration I didn't experiment yet. These things will go into their place when I try them, or anyone tells me "it works in the following way" The most important thing is that the connection ppp uses is not 8-bit yet. I believe it has something to do either with ssh configuration or the pty setup. In this configuration ssh uses the tilde (&tilde;) character as an escape character. It might stop or slow down the communication, as any newline-tilde sequence causes ssh to give a prompt. Ssh documentation said: &lt;On most systems, setting the escape character to ``none'' will also make the session transparent even if a tty is used.&gt; The corresponding flag to ssh is '<em>-e</em>', and you can also set it in the configuration file.
<sect1>Bandwith vs. cicles
<p>
Creating anything virtual comes with utilization of real-world resources. A VPN eats up bandwidth and computing resources. The goal would be to get balance between the two. You can tune it with the '-C' switch or the 'CompressionLevel' option. You might try using another cipher, but I don't recommend it. Also note that the round-trip-time can be longer if you use better compression. Any experiments on it are welcome.
<sect>Vulnerability analisis
<p>
I try to cover here the vulnerability issues arising from this particular setup and VPNs in general. Any comments are warmly welcome.
<itemize>
<item>sudo: Well, I'm excessively using sudo. I believe it's still safer than using setuid bits. It's still a backdraw of Linux that it hasn't got more fine-grained access control. Waiting for POSIX.6 compatibility &lt;http://www.xarius.demon.co.uk/software/posix6/&gt;. What is worse, there are shell scripts which are getting called through sudo. Bad enough. Any idea out there?
<item>pppd: It runs suid root also. It can be configured by user's .ppprc. There might be some nice buffer overruns in it. The bottom line: secure your slave account as tightly as you can.
<item>ssh: Beware that ssh older than 1.2.20 has security holes. What is worse, we made a configuration such when the master account had been compromised, the slave account is also compromised, and wide open to attacks using the two sudoed programs. It is because I've choosen not to have password on the master's secret key to enable automatic setup of the VPN.
<item>firewall: With inproperly set firewall rules on one bastion, you open both of the intranets. I recommend using IP masquerading (as setting up incorrect routes is a bit less trivial), and doing hard control on the VPN interfaces.
</itemize>
<sect1>About the ppp over ssh VPN technique
<p>
I developed this technique when there was no usable, standard
VPN for Linux. Now this is no longer the case.
At the time of writing this, you have the following alternatives:
If you want to use standard IPSEC VPN, you can use FreeS/WAN or pipsecd.
For PPTP you can use PoPToP (but be aware that PPTP protocol has
weaknesses). It is also worth to mention CIPE which is a lightweight
alternative for IPSEC.
<p>
This wide range of alternatives means that the ssh/ppp implementation
described in this howto is in the most cases not the best solution.
This is due the fact that this implementation is complex to set up
and has performance problems because of its tcp based nature.
<p>
I believe that the ssh/ppp technique is no longer beneficial for
building a VPN for non-illegal purposes in most cases, so I have
discontinued maintaining this HOWTO.
</article>

1222
LDP/retired/WWW-HOWTO.sgml Normal file
View File

File diff suppressed because it is too large Load Diff