mirror of https://github.com/tLDP/LDP
Merge pull request #52 from martin-a-brown/master
retired documents; migration scripts
This commit is contained in:
Martin A. Brown
commit
c5b627f27a
|
|
@ -0,0 +1,173 @@
|
|||
#! /usr/bin/python
|
||||
#
|
||||
# -- migrate to the new naming scheme
|
||||
|
||||
from __future__ import absolute_import, division, print_function
|
||||
|
||||
import os
|
||||
import sys
|
||||
import time
|
||||
import errno
|
||||
import shutil
|
||||
import logging
|
||||
import functools
|
||||
|
||||
logformat = '%(levelname)-9s %(name)s %(filename)s#%(lineno)s ' \
|
||||
+ '%(funcName)s %(message)s'
|
||||
logging.basicConfig(stream=sys.stderr, format=logformat, level=logging.DEBUG)
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# -- short names
|
||||
#
|
||||
opa = os.path.abspath
|
||||
opb = os.path.basename
|
||||
opd = os.path.dirname
|
||||
opj = os.path.join
|
||||
opn = os.path.normpath
|
||||
opr = os.path.relpath
|
||||
ops = os.path.split
|
||||
|
||||
faqdocs = '''Ftape-FAQ
|
||||
Linux-RAID-FAQ
|
||||
LDP-FAQ
|
||||
AfterStep-FAQ'''.split()
|
||||
|
||||
|
||||
def validate_args(argv):
|
||||
if len(argv) == 4:
|
||||
for d in argv[:3]:
|
||||
if not os.path.isdir(d):
|
||||
return False
|
||||
return True
|
||||
return False
|
||||
|
||||
|
||||
def collect_published_stems(dirbase):
|
||||
d = dict()
|
||||
for stem in os.listdir(dirbase):
|
||||
if not os.path.isdir(opj(dirbase, stem)):
|
||||
continue
|
||||
d[stem] = stem
|
||||
return d
|
||||
|
||||
|
||||
def make_refresh(target, title, delay=0):
|
||||
text = '''<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<title>{1}: {0}</title>
|
||||
<meta http-equiv="refresh" content="{2};URL='{0}'" />
|
||||
</head>
|
||||
<body>
|
||||
<p>This page has moved permanently to
|
||||
<a href="{0}">{0}</a>.
|
||||
Update your bookmarks if you wish. The compatibility
|
||||
redirect will remain through, at least, early 2017.
|
||||
</p>
|
||||
</body>
|
||||
</html>
|
||||
'''
|
||||
return text.format(target, title, delay)
|
||||
|
||||
def swapfiles(a, b):
|
||||
'''use os.rename() to make "a" become "b"'''
|
||||
if not os.path.isfile(a):
|
||||
raise OSError(errno.ENOENT, os.strerror(errno.ENOENT), a)
|
||||
tf = None
|
||||
if os.path.exists(b):
|
||||
_, tf = mkstemp(prefix='swapfile-', dir=opd(opa(a)))
|
||||
logger.debug("Created tempfile %s.", tf)
|
||||
logger.debug("About to rename %s to %s.", b, tf)
|
||||
os.rename(b, tf)
|
||||
logger.debug("About to rename %s to %s.", a, b)
|
||||
os.rename(a, b)
|
||||
if tf:
|
||||
logger.debug("About to rename %s to %s.", tf, a)
|
||||
os.rename(tf, a)
|
||||
logger.debug("About to remove %s.", tf)
|
||||
os.rmdir(tf)
|
||||
|
||||
|
||||
def create_symlink(source, target):
|
||||
assert not os.path.exists(target)
|
||||
targetdir = os.path.dirname(target)
|
||||
if not os.path.isdir(targetdir):
|
||||
logger.debug("Creating directory %s", targetdir)
|
||||
os.makedirs(targetdir)
|
||||
logger.debug("Creating symlink %s, pointing to %s", target, source)
|
||||
os.symlink(os.path.relpath(source, start=targetdir), target)
|
||||
|
||||
|
||||
def create_refresh_meta_equiv(fname, url, stem, **kwargs):
|
||||
assert not os.path.exists(fname)
|
||||
targetdir = os.path.dirname(fname)
|
||||
if not os.path.isdir(targetdir):
|
||||
logger.debug("Creating directory %s", targetdir)
|
||||
os.makedirs(targetdir)
|
||||
logger.debug("Creating file %s, with redirect to %s", fname, url)
|
||||
with open(fname, 'w') as f:
|
||||
f.write(make_refresh(url, stem, **kwargs))
|
||||
|
||||
|
||||
def newhtmlfilename(pubdir, stem, fname):
|
||||
sought = opj(pubdir, stem, fname)
|
||||
if not os.path.isfile(sought):
|
||||
return opj(pubdir, stem, 'index.html')
|
||||
return sought
|
||||
|
||||
|
||||
def faqs(stems, faqpath, faqcompat, pubdir, urlbase):
|
||||
|
||||
for stem in faqdocs:
|
||||
if stem not in stems:
|
||||
logger.critical("Stem %s not found in %s.", stem, pubdir)
|
||||
sys.exit(1)
|
||||
|
||||
# -- PDF handling
|
||||
newpdf = opj(pubdir, stem, stem + '.pdf')
|
||||
oldpdf = opj(faqcompat, 'pdf', stem + '.pdf')
|
||||
if os.path.exists(oldpdf):
|
||||
assert os.path.exists(oldpdf)
|
||||
assert os.path.exists(newpdf)
|
||||
os.rename(oldpdf, oldpdf + '.' + str(int(time.time())))
|
||||
create_symlink(newpdf, oldpdf)
|
||||
|
||||
# -- HTML handling
|
||||
htmldir = opj(faqcompat, stem)
|
||||
if os.path.isdir(htmldir):
|
||||
# -- LDP-FAQ and Linux-RAID-FAQ
|
||||
for fn in os.listdir(htmldir):
|
||||
if not fn.endswith('.html'):
|
||||
continue
|
||||
pubpath = newhtmlfilename(pubdir, stem, fn)
|
||||
url = pubpath.replace(pubdir, urlbase)
|
||||
fullname = opj(htmldir, fn)
|
||||
os.rename(fullname, fullname + '.' + str(int(time.time())))
|
||||
create_refresh_meta_equiv(fullname, url, stem, delay=2)
|
||||
else:
|
||||
# -- AfterStep-FAQ and Ftape-FAQ
|
||||
htmldir = faqcompat
|
||||
for fn in os.listdir(htmldir):
|
||||
if not fn.startswith(stem):
|
||||
continue
|
||||
pubpath = newhtmlfilename(pubdir, stem, fn)
|
||||
url = pubpath.replace(pubdir, urlbase)
|
||||
fullname = opj(htmldir, fn)
|
||||
os.rename(fullname, fullname + '.' + str(int(time.time())))
|
||||
create_refresh_meta_equiv(fullname, url, stem, delay=2)
|
||||
|
||||
|
||||
def main(fin, fout, argv):
|
||||
me = os.path.basename(sys.argv[0])
|
||||
usage = "usage: %s <faqpath> <faqcompat> <pubdir> <urlbase>" % (me,)
|
||||
if not validate_args(argv):
|
||||
return usage
|
||||
faqpath, faqcompat, pubdir, urlbase = argv
|
||||
stems = collect_published_stems(pubdir)
|
||||
faqs(stems, faqpath, faqcompat, pubdir, urlbase)
|
||||
return os.EX_OK
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
sys.exit(main(sys.stdin, sys.stdout, sys.argv[1:]))
|
||||
|
||||
# -- end of file
|
||||
|
|
@ -0,0 +1,52 @@
|
|||
#! /bin/bash
|
||||
|
||||
set -e
|
||||
set -x
|
||||
|
||||
squawk () { printf >&2 "%s\n" "$@"; }
|
||||
abort () { squawk "$@" ; exit 1; }
|
||||
|
||||
SELFNAME="$( readlink --canonicalize ${0})"
|
||||
ME="${SELFNAME##*/}" # -- basename
|
||||
HERE="${SELFNAME%/*}" # -- dirname
|
||||
|
||||
# -- SET THIS VARIABLE to the full path of the LDP content
|
||||
#
|
||||
CONTENTROOT=/home/mabrown/wip/tldp/website/html
|
||||
|
||||
# -- trailing slash, atypically included on PUBDIR, here
|
||||
PUBDIR="${CONTENTROOT}/en/"
|
||||
|
||||
cd "$CONTENTROOT"
|
||||
|
||||
READY=yes
|
||||
for D in REF FAQ LDP HOWTO; do
|
||||
if ! test -d "${D}"; then
|
||||
squawk "Could not find directory ${D}."
|
||||
READY=no
|
||||
fi
|
||||
if ! test -d "${D}.compat"; then
|
||||
squawk "Could not find directory ${D}.compat."
|
||||
READY=no
|
||||
fi
|
||||
done
|
||||
|
||||
if test "$READY" != "yes"; then
|
||||
abort "Cowardly, refusing to throw the switch."
|
||||
fi
|
||||
|
||||
for D in REF FAQ LDP HOWTO; do
|
||||
|
||||
squawk "Activating new ${D}."
|
||||
|
||||
mv -v "${D}" "old.${D}" && mv -v "${D}.compat" "${D}"
|
||||
|
||||
squawk "Activated new ${D}."
|
||||
|
||||
done
|
||||
|
||||
squawk "Done. Success."
|
||||
|
||||
exit 0
|
||||
|
||||
# -- end of file
|
||||
|
|
@ -0,0 +1,213 @@
|
|||
#! /usr/bin/python
|
||||
#
|
||||
# -- migrate to the new naming scheme
|
||||
|
||||
from __future__ import absolute_import, division, print_function
|
||||
|
||||
import os
|
||||
import sys
|
||||
import time
|
||||
import errno
|
||||
import shutil
|
||||
import logging
|
||||
import functools
|
||||
|
||||
logformat = '%(levelname)-9s %(name)s %(filename)s#%(lineno)s ' \
|
||||
+ '%(funcName)s %(message)s'
|
||||
logging.basicConfig(stream=sys.stderr, format=logformat, level=logging.DEBUG)
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# -- short names
|
||||
#
|
||||
opa = os.path.abspath
|
||||
opb = os.path.basename
|
||||
opd = os.path.dirname
|
||||
opj = os.path.join
|
||||
opn = os.path.normpath
|
||||
opr = os.path.relpath
|
||||
ops = os.path.split
|
||||
|
||||
|
||||
# -- Stem handling for HTML
|
||||
|
||||
predictably_named_guides = '''Bash-Beginners-Guide
|
||||
cpg
|
||||
espk-ug
|
||||
EVMSUG
|
||||
GNU-Linux-Tools-Summary
|
||||
LDP-Author-Guide
|
||||
Linux-Dictionary
|
||||
Linux-Filesystem-Hierarchy
|
||||
Linux-Media-Guide
|
||||
Mobile-Guide
|
||||
Pocket-Linux-Guide
|
||||
sag'''.split()
|
||||
|
||||
stems = dict(zip(predictably_named_guides, predictably_named_guides))
|
||||
|
||||
# -- no "html" subdirectory
|
||||
#
|
||||
stems['lki'] = 'lki'
|
||||
stems['nag2'] = 'nag2'
|
||||
|
||||
# -- two kernel versions, same name (in days of yore)
|
||||
#
|
||||
stems['lkmpg/2.4'] = 'lkmpg-2.4'
|
||||
stems['lkmpg/2.6'] = 'lkmpg-2.6'
|
||||
|
||||
# -- wacky path naming
|
||||
#
|
||||
stems['lame/LAME/linux-admin-made-easy'] = 'lame'
|
||||
stems['solrhe/Securing-Optimizing-Linux-RH-Edition-v1.3'] = 'solrhe'
|
||||
|
||||
# -- name changers
|
||||
#
|
||||
stems['abs'] = 'abs-guide'
|
||||
stems['intro-linux'] = 'Intro-Linux'
|
||||
|
||||
|
||||
# -- PDF handling
|
||||
|
||||
pdflist = '''Bash-Beginners-Guide/Bash-Beginners-Guide.pdf
|
||||
EVMSUG/EVMSUG.pdf
|
||||
GNU-Linux-Tools-Summary/GNU-Linux-Tools-Summary.pdf
|
||||
LDP-Author-Guide/LDP-Author-Guide.pdf
|
||||
Linux-Dictionary/Linux-Dictionary.pdf
|
||||
Linux-Filesystem-Hierarchy/Linux-Filesystem-Hierarchy.pdf
|
||||
Linux-Media-Guide/Linux-Media-Guide.pdf
|
||||
Mobile-Guide/Mobile-Guide.pdf
|
||||
Pocket-Linux-Guide/Pocket-Linux-Guide.pdf
|
||||
cpg/Custom-Porting-Guide.pdf
|
||||
espk-ug/espk-ug.pdf
|
||||
lame/lame.pdf
|
||||
lki/lki.pdf
|
||||
nag2/nag2.pdf
|
||||
sag/sag.pdf
|
||||
solrhe/Securing-Optimizing-Linux-RH-Edition-v1.3.pdf'''.split()
|
||||
|
||||
extrapdfs = dict()
|
||||
extrapdfs['lkmpg/2.4/lkmpg.pdf'] = 'lkmpg-2.4'
|
||||
extrapdfs['lkmpg/2.6/lkmpg.pdf'] = 'lkmpg-2.6'
|
||||
extrapdfs['abs/abs-guide.pdf'] = 'abs-guide'
|
||||
extrapdfs['intro-linux/intro-linux.pdf'] = 'Intro-Linux'
|
||||
|
||||
def validate_args(argv):
|
||||
if len(argv) == 4:
|
||||
for d in argv[:3]:
|
||||
if not os.path.isdir(d):
|
||||
return False
|
||||
return True
|
||||
return False
|
||||
|
||||
|
||||
def make_refresh(target, title, delay=0):
|
||||
text = '''<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<title>{1}: {0}</title>
|
||||
<meta http-equiv="refresh" content="{2};URL='{0}'" />
|
||||
</head>
|
||||
<body>
|
||||
<p>This page has moved permanently to
|
||||
<a href="{0}">{0}</a>.
|
||||
Update your bookmarks if you wish. The compatibility
|
||||
redirect will remain through, at least, early 2017.
|
||||
</p>
|
||||
</body>
|
||||
</html>
|
||||
'''
|
||||
return text.format(target, title, delay)
|
||||
|
||||
def swapfiles(a, b):
|
||||
'''use os.rename() to make "a" become "b"'''
|
||||
if not os.path.isfile(a):
|
||||
raise OSError(errno.ENOENT, os.strerror(errno.ENOENT), a)
|
||||
tf = None
|
||||
if os.path.exists(b):
|
||||
_, tf = mkstemp(prefix='swapfile-', dir=opd(opa(a)))
|
||||
logger.debug("Created tempfile %s.", tf)
|
||||
logger.debug("About to rename %s to %s.", b, tf)
|
||||
os.rename(b, tf)
|
||||
logger.debug("About to rename %s to %s.", a, b)
|
||||
os.rename(a, b)
|
||||
if tf:
|
||||
logger.debug("About to rename %s to %s.", tf, a)
|
||||
os.rename(tf, a)
|
||||
logger.debug("About to remove %s.", tf)
|
||||
os.rmdir(tf)
|
||||
|
||||
|
||||
def create_symlink(source, target):
|
||||
assert not os.path.exists(target)
|
||||
targetdir = os.path.dirname(target)
|
||||
if not os.path.isdir(targetdir):
|
||||
logger.debug("Creating directory %s", targetdir)
|
||||
os.makedirs(targetdir)
|
||||
logger.debug("Creating symlink %s, pointing to %s", target, source)
|
||||
os.symlink(os.path.relpath(source, start=targetdir), target)
|
||||
|
||||
|
||||
def create_refresh_meta_equiv(fname, url, stem, **kwargs):
|
||||
assert not os.path.exists(fname)
|
||||
targetdir = os.path.dirname(fname)
|
||||
if not os.path.isdir(targetdir):
|
||||
logger.debug("Creating directory %s", targetdir)
|
||||
os.makedirs(targetdir)
|
||||
logger.debug("Creating file %s, with redirect to %s", fname, url)
|
||||
with open(fname, 'w') as f:
|
||||
f.write(make_refresh(url, stem, **kwargs))
|
||||
|
||||
|
||||
def newhtmlfilename(pubdir, stem, fname):
|
||||
sought = opj(pubdir, stem, fname)
|
||||
if not os.path.isfile(sought):
|
||||
return opj(pubdir, stem, 'index.html')
|
||||
return sought
|
||||
|
||||
def guides(stems, guidepath, guidecompat, pubdir, urlbase):
|
||||
|
||||
for pdf in pdflist:
|
||||
stem, _ = os.path.split(pdf)
|
||||
oldpdf = opj(guidecompat, pdf)
|
||||
newpdf = opj(pubdir, stem, stem + '.pdf')
|
||||
assert os.path.exists(oldpdf)
|
||||
assert os.path.exists(newpdf)
|
||||
os.rename(oldpdf, oldpdf + '.' + str(int(time.time())))
|
||||
create_symlink(newpdf, oldpdf)
|
||||
|
||||
for pdf, stem in extrapdfs.items():
|
||||
oldpdf = opj(guidecompat, pdf)
|
||||
newpdf = opj(pubdir, stem, stem + '.pdf')
|
||||
assert os.path.exists(oldpdf)
|
||||
assert os.path.exists(newpdf)
|
||||
os.rename(oldpdf, oldpdf + '.' + str(int(time.time())))
|
||||
create_symlink(newpdf, oldpdf)
|
||||
|
||||
for stem, newstem in sorted(stems.items(), key=lambda x: x[1].lower()):
|
||||
htmldir = opj(guidecompat, stem, 'html')
|
||||
if not os.path.isdir(htmldir):
|
||||
htmldir, _ = os.path.split(htmldir)
|
||||
assert os.path.exists(htmldir)
|
||||
for fn in os.listdir(htmldir):
|
||||
if not fn.endswith('.html'):
|
||||
continue
|
||||
pubpath = newhtmlfilename(pubdir, newstem, fn)
|
||||
url = pubpath.replace(pubdir, urlbase)
|
||||
fullname = opj(htmldir, fn)
|
||||
os.rename(fullname, fullname + '.' + str(int(time.time())))
|
||||
create_refresh_meta_equiv(fullname, url, newstem, delay=2)
|
||||
|
||||
|
||||
def main(fin, fout, argv):
|
||||
me = os.path.basename(sys.argv[0])
|
||||
usage = "usage: %s <guidepath> <guidecompat> <pubdir> <urlbase>" % (me,)
|
||||
if not validate_args(argv):
|
||||
return usage
|
||||
guidepath, guidecompat, pubdir, urlbase = argv
|
||||
guides(stems, guidepath, guidecompat, pubdir, urlbase)
|
||||
return os.EX_OK
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
sys.exit(main(sys.stdin, sys.stdout, sys.argv[1:]))
|
||||
|
||||
# -- end of file
|
||||
|
|
@ -0,0 +1,313 @@
|
|||
#! /usr/bin/python
|
||||
#
|
||||
# -- migrate to the new naming scheme
|
||||
|
||||
from __future__ import absolute_import, division, print_function
|
||||
|
||||
import os
|
||||
import sys
|
||||
import errno
|
||||
import shutil
|
||||
import logging
|
||||
import functools
|
||||
|
||||
logformat = '%(levelname)-9s %(name)s %(filename)s#%(lineno)s ' \
|
||||
+ '%(funcName)s %(message)s'
|
||||
logging.basicConfig(stream=sys.stderr, format=logformat, level=logging.DEBUG)
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# -- short names
|
||||
#
|
||||
opa = os.path.abspath
|
||||
opb = os.path.basename
|
||||
opd = os.path.dirname
|
||||
opj = os.path.join
|
||||
opn = os.path.normpath
|
||||
opr = os.path.relpath
|
||||
ops = os.path.split
|
||||
|
||||
SKIP = object()
|
||||
|
||||
|
||||
def add_renamed_stems(stems):
|
||||
stems['ppp-ssh'] = 'VPN-PPP-SSH-HOWTO'
|
||||
stems['intro-linux'] = 'Intro-Linux'
|
||||
stems['DPT-Hardware-RAID'] = 'DPT-Hardware-RAID-HOWTO'
|
||||
stems['Loadlin+Win95'] = 'Loadlin+Win95-98-ME'
|
||||
stems['Laptop-HOWTO'] = 'Mobile-Guide'
|
||||
stems['IR-HOWTO'] = 'Infrared-HOWTO'
|
||||
stems['Xnews-under-Linux-HOWTO'] = 'Windows-Newsreaders-under-Linux-HOWTO'
|
||||
stems['Access-HOWTO'] = 'Accessibility-HOWTO'
|
||||
stems['Adv-Bash-Scr-HOWTO'] = 'abs-guide'
|
||||
stems['abs'] = 'abs-guide'
|
||||
stems['Mosix-HOWTO'] = 'openMosix-HOWTO'
|
||||
stems['Partition-Rescue-New'] = 'Partition-Rescue'
|
||||
stems['Partition-Mass-Storage-Dummies-Linux-HOWTO'] = 'Partition-Mass-Storage-Definitions-Naming-HOWTO'
|
||||
|
||||
|
||||
def add_skipped_stems(stems):
|
||||
stems['index.html'] = SKIP
|
||||
stems['INDEX'] = SKIP
|
||||
stems['README'] = SKIP
|
||||
stems['COPYRIGHT'] = SKIP
|
||||
stems['.htaccess'] = SKIP
|
||||
stems['GCC-HOWTO'] = SKIP
|
||||
stems['Netscape+Proxy'] = SKIP
|
||||
stems['Sendmail+UUCP'] = SKIP
|
||||
stems['GTEK-BBS-550'] = SKIP
|
||||
stems['Consultants-HOWTO'] = SKIP
|
||||
stems['Acer-Laptop-HOWTO'] = SKIP
|
||||
stems['Linux-From-Scratch-HOWTO'] = SKIP
|
||||
stems['Distributions-HOWTO'] = SKIP
|
||||
stems['MIPS-HOWTO'] = SKIP
|
||||
stems['3Dfx-HOWTO'] = SKIP
|
||||
stems['PostgreSQL-HOWTO'] = SKIP
|
||||
stems['Term-Firewall'] = SKIP
|
||||
stems['WikiText-HOWTO'] = SKIP
|
||||
stems['HOWTO-INDEX'] = SKIP
|
||||
stems['HOWTO-HOWTO'] = SKIP
|
||||
stems['Security-Quickstart-Redhat-HOWTO'] = SKIP
|
||||
|
||||
|
||||
def collect_published_stems(dirbase):
|
||||
d = dict()
|
||||
for stem in os.listdir(dirbase):
|
||||
if not os.path.isdir(opj(dirbase, stem)):
|
||||
continue
|
||||
d[stem] = stem
|
||||
add_renamed_stems(d)
|
||||
add_skipped_stems(d)
|
||||
return d
|
||||
|
||||
|
||||
def validate_args(argv):
|
||||
if len(argv) == 4:
|
||||
for d in argv[:3]:
|
||||
if not os.path.isdir(d):
|
||||
return False
|
||||
return True
|
||||
return False
|
||||
|
||||
|
||||
def walk_simple(stems, dirbase, root):
|
||||
for name in os.listdir(dirbase):
|
||||
if name.endswith('.pdf'):
|
||||
stem, _ = os.path.splitext(name)
|
||||
else:
|
||||
stem = name
|
||||
relpath = opr(opj(dirbase, name), start=root)
|
||||
newstem = stems.get(stem, None)
|
||||
if newstem is None:
|
||||
logger.error("%s missing stem: %s", stem, relpath)
|
||||
continue
|
||||
elif newstem is SKIP:
|
||||
logger.info("%s ignoring stem: %s", stem, relpath)
|
||||
continue
|
||||
yield newstem, relpath
|
||||
|
||||
|
||||
def walk_html_single(stems, dirbase, root):
|
||||
for name in os.listdir(dirbase):
|
||||
if name == 'images':
|
||||
continue
|
||||
dirname = opj(dirbase, name)
|
||||
if not os.path.isdir(dirname):
|
||||
continue
|
||||
indexhtml = opj(dirname, 'index.html')
|
||||
if not os.path.isfile(indexhtml):
|
||||
logger.error("%s missing index.html: %s", stem, indexhtml)
|
||||
stem = name
|
||||
relpath = opr(indexhtml, start=root)
|
||||
newstem = stems.get(stem, None)
|
||||
if newstem is None:
|
||||
logger.error("%s missing stem: %s", stem, relpath)
|
||||
continue
|
||||
elif newstem is SKIP:
|
||||
logger.info("%s ignoring stem: %s", stem, relpath)
|
||||
continue
|
||||
yield newstem, relpath
|
||||
|
||||
|
||||
def walk_html_chunked_dirs(stems, dirbase, root):
|
||||
for name in os.listdir(dirbase):
|
||||
if name in ('images', 'pdf', 'text', 'html_single', 'archived'):
|
||||
continue
|
||||
dirname = opj(dirbase, name)
|
||||
if not os.path.isdir(dirname):
|
||||
continue
|
||||
for subname in os.listdir(dirname):
|
||||
fname = opj(dirname, subname)
|
||||
if os.path.isdir(fname):
|
||||
continue
|
||||
stem = name
|
||||
relpath = opr(fname, start=root)
|
||||
newstem = stems.get(stem, None)
|
||||
if newstem is None:
|
||||
logger.error("%s missing stem: %s", stem, relpath)
|
||||
continue
|
||||
elif newstem is SKIP:
|
||||
logger.info("%s ignoring stem: %s", stem, relpath)
|
||||
continue
|
||||
yield newstem, relpath
|
||||
|
||||
|
||||
def walk_html_chunked_files(stems, dirbase, root):
|
||||
for name in os.listdir(dirbase):
|
||||
fname = opj(dirbase, name)
|
||||
if not os.path.isfile(fname):
|
||||
continue
|
||||
stem, ext = os.path.splitext(name)
|
||||
if stem == 'index' or ext != '.html':
|
||||
continue
|
||||
if stem not in stems:
|
||||
stem = '-'.join(stem.split('-')[:-1])
|
||||
if stem not in stems:
|
||||
logger.error("Could not determine stem for %s", fname)
|
||||
continue
|
||||
relpath = opr(fname, start=root)
|
||||
newstem = stems.get(stem, None)
|
||||
if newstem is None:
|
||||
logger.error("%s missing stem: %s", stem, relpath)
|
||||
continue
|
||||
elif newstem is SKIP:
|
||||
logger.info("%s ignoring stem: %s", stem, relpath)
|
||||
continue
|
||||
yield newstem, relpath
|
||||
|
||||
|
||||
def htmlf(stem, relpath, pubdir, newtree):
|
||||
pubf = opj(pubdir, stem, relpath)
|
||||
newf = opj(newtree, relpath)
|
||||
if os.path.exists(pubf):
|
||||
return stem, relpath, newf, pubf
|
||||
else:
|
||||
return stem, relpath, newf, opj(pubdir, stem, 'index.html')
|
||||
|
||||
|
||||
def htmld(stem, relpath, pubdir, newtree):
|
||||
pubf = opj(pubdir, relpath)
|
||||
newf = opj(newtree, relpath)
|
||||
if os.path.exists(pubf):
|
||||
return stem, relpath, newf, pubf
|
||||
else:
|
||||
return stem, relpath, newf, opj(pubdir, stem, 'index.html')
|
||||
|
||||
|
||||
def htmls(stem, relpath, pubdir, newtree):
|
||||
pubf = opj(pubdir, stem, stem + '-single.html')
|
||||
newf = opj(newtree, relpath)
|
||||
if os.path.exists(pubf):
|
||||
return stem, relpath, newf, pubf
|
||||
else:
|
||||
return stem, relpath, newf, opj(pubdir, stem, 'index.html')
|
||||
|
||||
|
||||
def txt(stem, relpath, pubdir, newtree):
|
||||
pubf = opj(pubdir, stem, stem + '.txt')
|
||||
newf = opj(newtree, relpath)
|
||||
if os.path.exists(pubf):
|
||||
return stem, relpath, newf, pubf
|
||||
else:
|
||||
return stem, relpath, newf, None
|
||||
|
||||
|
||||
def pdf(stem, relpath, pubdir, newtree):
|
||||
pubf = opj(pubdir, stem, stem + '.pdf')
|
||||
newf = opj(newtree, relpath)
|
||||
if os.path.exists(pubf):
|
||||
return stem, relpath, newf, pubf
|
||||
else:
|
||||
return stem, relpath, newf, None
|
||||
|
||||
def make_refresh(target, title, delay=0):
|
||||
text = '''<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<title>{1}: {0}</title>
|
||||
<meta http-equiv="refresh" content="{2};URL='{0}'" />
|
||||
</head>
|
||||
<body>
|
||||
<p>This page has moved permanently to
|
||||
<a href="{0}">{0}</a>.
|
||||
Update your bookmarks if you wish. The compatibility
|
||||
redirect will remain through, at least, early 2017.
|
||||
</p>
|
||||
</body>
|
||||
</html>
|
||||
'''
|
||||
return text.format(target, title, delay)
|
||||
|
||||
|
||||
def create_symlink(source, target):
|
||||
assert not os.path.exists(target)
|
||||
targetdir = os.path.dirname(target)
|
||||
if not os.path.isdir(targetdir):
|
||||
logger.debug("Creating directory %s", targetdir)
|
||||
os.makedirs(targetdir)
|
||||
logger.debug("Creating symlink %s, pointing to %s", target, source)
|
||||
os.symlink(os.path.relpath(source, start=targetdir), target)
|
||||
|
||||
|
||||
def create_refresh_meta_equiv(fname, url, stem, **kwargs):
|
||||
assert not os.path.exists(fname)
|
||||
targetdir = os.path.dirname(fname)
|
||||
if not os.path.isdir(targetdir):
|
||||
logger.debug("Creating directory %s", targetdir)
|
||||
os.makedirs(targetdir)
|
||||
logger.debug("Creating file %s, with redirect to %s", fname, url)
|
||||
with open(fname, 'w') as f:
|
||||
f.write(make_refresh(url, stem, **kwargs))
|
||||
|
||||
|
||||
def howtos(stems, howtopath, newtree, pubdir, urlbase):
|
||||
ldptree = dict()
|
||||
for s, r in walk_html_chunked_files(stems, howtopath, howtopath):
|
||||
ldptree[r] = htmlf(s, r, pubdir, newtree)
|
||||
# print('chunked_files', s, r)
|
||||
|
||||
for s, r in walk_html_chunked_dirs(stems, howtopath, howtopath):
|
||||
ldptree[r] = htmld(s, r, pubdir, newtree)
|
||||
# print('chunked_dirs', s, r)
|
||||
|
||||
howto_htmls = opj(howtopath, 'html_single')
|
||||
for s, r in walk_html_single(stems, howto_htmls, howtopath):
|
||||
ldptree[r] = htmls(s, r, pubdir, newtree)
|
||||
# print('html_single', s, r)
|
||||
|
||||
for s, r in walk_simple(stems, opj(howtopath, 'text'), howtopath):
|
||||
ldptree[r] = txt(s, r, pubdir, newtree)
|
||||
# print('text', s, r)
|
||||
|
||||
for s, r in walk_simple(stems, opj(howtopath, 'pdf'), howtopath):
|
||||
ldptree[r] = pdf(s, r, pubdir, newtree)
|
||||
# print('pdf', s, r)
|
||||
|
||||
# -- have to symlink the PDF and TXT files
|
||||
#
|
||||
for fname in sorted(ldptree.keys(), key=lambda x: x.lower()):
|
||||
stem, relpath, newpath, pubpath = ldptree[fname]
|
||||
url = pubpath.replace(pubdir, urlbase)
|
||||
if fname.startswith('text/') or fname.startswith('pdf/'):
|
||||
create_symlink(pubpath, newpath)
|
||||
else:
|
||||
url = pubpath.replace(pubdir, urlbase)
|
||||
create_refresh_meta_equiv(newpath, url, stem, delay=2)
|
||||
|
||||
|
||||
def main(fin, fout, argv):
|
||||
me = os.path.basename(sys.argv[0])
|
||||
usage = "usage: %s <howtopath> <howtocompat> <pubdir> <urlbase>" % (me,)
|
||||
if not validate_args(argv):
|
||||
return usage
|
||||
howtopath, howtocompat, pubdir, urlbase = argv
|
||||
oldtree = opd(opn(howtopath))
|
||||
|
||||
stems = collect_published_stems(pubdir)
|
||||
|
||||
howtos(stems, howtopath, howtocompat, pubdir, urlbase)
|
||||
return os.EX_OK
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
sys.exit(main(sys.stdin, sys.stdout, sys.argv[1:]))
|
||||
|
||||
# -- end of file
|
||||
|
|
@ -0,0 +1,71 @@
|
|||
#! /bin/bash
|
||||
|
||||
set -e
|
||||
set -x
|
||||
|
||||
SELFNAME="$( readlink --canonicalize ${0})"
|
||||
ME="${SELFNAME##*/}" # -- basename
|
||||
HERE="${SELFNAME%/*}" # -- dirname
|
||||
|
||||
# -- SET THIS VARIABLE to the full path of the LDP content
|
||||
#
|
||||
CONTENTROOT=/home/mabrown/wip/tldp/website/html
|
||||
|
||||
# -- trailing slash, atypically included on PUBDIR, here
|
||||
PUBDIR="${CONTENTROOT}/en/"
|
||||
URL_PUBDIR=http://www.tldp.org/en/
|
||||
|
||||
cd "$CONTENTROOT"
|
||||
|
||||
# -- HOWTO handling: build symlinks and HTTP META-EQUIV files
|
||||
#
|
||||
HOWTOS="${CONTENTROOT}/HOWTO/"
|
||||
HOWTO_COMPAT=HOWTO.compat/
|
||||
HOWTO_MIGRATOR=${HERE}/howtomigration.py
|
||||
|
||||
test -d "${HOWTO_COMPAT}" \
|
||||
|| mkdir "${HOWTO_COMPAT}"
|
||||
HOWTO_COMPAT=$( readlink --canonicalize "$HOWTO_COMPAT" )
|
||||
python \
|
||||
"${HOWTO_MIGRATOR}" "${HOWTOS}" "${HOWTO_COMPAT}" "${PUBDIR}" "${URL_PUBDIR}"
|
||||
|
||||
|
||||
# -- guide handling: build symlinks and HTTP META-EQUIV files
|
||||
#
|
||||
GUIDES="${CONTENTROOT}/LDP/"
|
||||
GUIDE_COMPAT=LDP.compat/
|
||||
GUIDE_MIGRATOR=${HERE}/guidemigration.py
|
||||
|
||||
rsync --archive --verbose -- "${GUIDES}" "${GUIDE_COMPAT}"
|
||||
GUIDE_COMPAT=$( readlink --canonicalize "$GUIDE_COMPAT" )
|
||||
python \
|
||||
"${GUIDE_MIGRATOR}" "${GUIDES}" "${GUIDE_COMPAT}" "${PUBDIR}" "${URL_PUBDIR}"
|
||||
|
||||
|
||||
# -- ref handling: build symlinks and HTTP META-EQUIV files
|
||||
#
|
||||
REFS="${CONTENTROOT}/REF/"
|
||||
REF_COMPAT=REF.compat/
|
||||
REF_MIGRATOR=${HERE}/refmigration.py
|
||||
|
||||
rsync --archive --verbose -- "${REFS}" "${REF_COMPAT}"
|
||||
REF_COMPAT=$( readlink --canonicalize "$REF_COMPAT" )
|
||||
python \
|
||||
"${REF_MIGRATOR}" "${REFS}" "${REF_COMPAT}" "${PUBDIR}" "${URL_PUBDIR}"
|
||||
|
||||
|
||||
# -- ref handling: build symlinks and HTTP META-EQUIV files
|
||||
#
|
||||
FAQS="${CONTENTROOT}/FAQ/"
|
||||
FAQ_COMPAT=FAQ.compat/
|
||||
FAQ_MIGRATOR=${HERE}/faqmigration.py
|
||||
|
||||
rsync --archive --verbose -- "${FAQS}" "${FAQ_COMPAT}"
|
||||
FAQ_COMPAT=$( readlink --canonicalize "$FAQ_COMPAT" )
|
||||
python \
|
||||
"${FAQ_MIGRATOR}" "${FAQS}" "${FAQ_COMPAT}" "${PUBDIR}" "${URL_PUBDIR}"
|
||||
|
||||
|
||||
exit 0
|
||||
|
||||
# -- end of file
|
||||
|
|
@ -0,0 +1,66 @@
|
|||
#! /bin/bash
|
||||
|
||||
set -e
|
||||
set -x
|
||||
|
||||
SELFNAME="$( readlink --canonicalize ${0})"
|
||||
ME="${SELFNAME##*/}" # -- basename
|
||||
DIR="${SELFNAME%/*}" # -- dirname
|
||||
|
||||
CONTENTROOT=/home/mabrown/wip/tldp/website/html
|
||||
cd "$CONTENTROOT"
|
||||
|
||||
# -- minor cleanup of dangling or otherwise broken symlinks:
|
||||
for LINK in \
|
||||
html/pub/Linux/docs/HOWTO/translations/polish/.message \
|
||||
html/pub/Linux/docs/HOWTO/translations/pl/.message \
|
||||
html/LDP/LGNET/182/184 \
|
||||
; do
|
||||
|
||||
test -L "$LINK" && rm -f "$LINK"
|
||||
|
||||
done
|
||||
|
||||
ARCHIVE=archive
|
||||
test -d "${ARCHIVE}" \
|
||||
|| mkdir "${ARCHIVE}"
|
||||
|
||||
# -- populate the archive with retired items
|
||||
#
|
||||
mv \
|
||||
--target-directory "${ARCHIVE}" \
|
||||
--verbose \
|
||||
-- \
|
||||
HOWTO/Netscape+Proxy.html \
|
||||
HOWTO/Sendmail+UUCP.html \
|
||||
HOWTO/GTEK-BBS-550.html \
|
||||
HOWTO/DPT-Hardware-RAID.html \
|
||||
HOWTO/Consultants-HOWTO.html \
|
||||
HOWTO/WikiText-HOWTO \
|
||||
HOWTO/Security-Quickstart-Redhat-HOWTO \
|
||||
REF/palmdevqs \
|
||||
REF/ls_quickref \
|
||||
REF/Joe-Command-Reference \
|
||||
FAQ/Linux-FAQ \
|
||||
FAQ/sig11 \
|
||||
FAQ/Threads-FAQ \
|
||||
FAQ/WordPerfect-Linux-FAQ \
|
||||
|
||||
# -- and toss aside the neolithically-ancient crap
|
||||
#
|
||||
TODELETE=todelete-$( date +%F )
|
||||
test -d "${TODELETE}" \
|
||||
|| mkdir "${TODELETE}"
|
||||
|
||||
mv \
|
||||
--target-directory "${TODELETE}" \
|
||||
--verbose \
|
||||
-- \
|
||||
HOWTO/Acer-Laptop-HOWTO.html \
|
||||
HOWTO/Linux-From-Scratch-HOWTO.html \
|
||||
HOWTO/Distributions-HOWTO.html \
|
||||
HOWTO/MIPS-HOWTO.html \
|
||||
HOWTO/3Dfx-HOWTO.html \
|
||||
HOWTO/PostgreSQL-HOWTO.html \
|
||||
|
||||
# -- end of file
|
||||
|
|
@ -0,0 +1,172 @@
|
|||
#! /usr/bin/python
|
||||
#
|
||||
# -- migrate to the new naming scheme
|
||||
|
||||
from __future__ import absolute_import, division, print_function
|
||||
|
||||
import os
|
||||
import sys
|
||||
import time
|
||||
import errno
|
||||
import shutil
|
||||
import logging
|
||||
import functools
|
||||
|
||||
logformat = '%(levelname)-9s %(name)s %(filename)s#%(lineno)s ' \
|
||||
+ '%(funcName)s %(message)s'
|
||||
logging.basicConfig(stream=sys.stderr, format=logformat, level=logging.DEBUG)
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# -- short names
|
||||
#
|
||||
opa = os.path.abspath
|
||||
opb = os.path.basename
|
||||
opd = os.path.dirname
|
||||
opj = os.path.join
|
||||
opn = os.path.normpath
|
||||
opr = os.path.relpath
|
||||
ops = os.path.split
|
||||
|
||||
refdocs = '''CVS-BestPractices
|
||||
VideoLAN-Quickstart
|
||||
VLC-User-Guide
|
||||
VLS-User-Guide
|
||||
INTRO/Backup-INTRO
|
||||
INTRO/Intrusion-INTRO
|
||||
INTRO/PhysSecurity-INTRO
|
||||
INTRO/SecuringData-INTRO
|
||||
INTRO/Virus-INTRO'''.split()
|
||||
|
||||
|
||||
def validate_args(argv):
|
||||
if len(argv) == 4:
|
||||
for d in argv[:3]:
|
||||
if not os.path.isdir(d):
|
||||
return False
|
||||
return True
|
||||
return False
|
||||
|
||||
|
||||
def collect_published_stems(dirbase):
|
||||
d = dict()
|
||||
for stem in os.listdir(dirbase):
|
||||
if not os.path.isdir(opj(dirbase, stem)):
|
||||
continue
|
||||
d[stem] = stem
|
||||
# add_renamed_stems(d)
|
||||
# add_skipped_stems(d)
|
||||
return d
|
||||
|
||||
|
||||
def make_refresh(target, title, delay=0):
|
||||
text = '''<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<title>{1}: {0}</title>
|
||||
<meta http-equiv="refresh" content="{2};URL='{0}'" />
|
||||
</head>
|
||||
<body>
|
||||
<p>This page has moved permanently to
|
||||
<a href="{0}">{0}</a>.
|
||||
Update your bookmarks if you wish. The compatibility
|
||||
redirect will remain through, at least, early 2017.
|
||||
</p>
|
||||
</body>
|
||||
</html>
|
||||
'''
|
||||
return text.format(target, title, delay)
|
||||
|
||||
def swapfiles(a, b):
|
||||
'''use os.rename() to make "a" become "b"'''
|
||||
if not os.path.isfile(a):
|
||||
raise OSError(errno.ENOENT, os.strerror(errno.ENOENT), a)
|
||||
tf = None
|
||||
if os.path.exists(b):
|
||||
_, tf = mkstemp(prefix='swapfile-', dir=opd(opa(a)))
|
||||
logger.debug("Created tempfile %s.", tf)
|
||||
logger.debug("About to rename %s to %s.", b, tf)
|
||||
os.rename(b, tf)
|
||||
logger.debug("About to rename %s to %s.", a, b)
|
||||
os.rename(a, b)
|
||||
if tf:
|
||||
logger.debug("About to rename %s to %s.", tf, a)
|
||||
os.rename(tf, a)
|
||||
logger.debug("About to remove %s.", tf)
|
||||
os.rmdir(tf)
|
||||
|
||||
|
||||
def create_symlink(source, target):
|
||||
assert not os.path.exists(target)
|
||||
targetdir = os.path.dirname(target)
|
||||
if not os.path.isdir(targetdir):
|
||||
logger.debug("Creating directory %s", targetdir)
|
||||
os.makedirs(targetdir)
|
||||
logger.debug("Creating symlink %s, pointing to %s", target, source)
|
||||
os.symlink(os.path.relpath(source, start=targetdir), target)
|
||||
|
||||
|
||||
def create_refresh_meta_equiv(fname, url, stem, **kwargs):
|
||||
assert not os.path.exists(fname)
|
||||
targetdir = os.path.dirname(fname)
|
||||
if not os.path.isdir(targetdir):
|
||||
logger.debug("Creating directory %s", targetdir)
|
||||
os.makedirs(targetdir)
|
||||
logger.debug("Creating file %s, with redirect to %s", fname, url)
|
||||
with open(fname, 'w') as f:
|
||||
f.write(make_refresh(url, stem, **kwargs))
|
||||
|
||||
|
||||
def newhtmlfilename(pubdir, stem, fname):
|
||||
sought = opj(pubdir, stem, fname)
|
||||
if not os.path.isfile(sought):
|
||||
return opj(pubdir, stem, 'index.html')
|
||||
return sought
|
||||
|
||||
|
||||
def refs(stems, refpath, refcompat, pubdir, urlbase):
|
||||
|
||||
for doc in refdocs:
|
||||
stem = doc.replace('INTRO/', '')
|
||||
if stem not in stems:
|
||||
logger.critical("Stem %s not found in %s.", stem, pubdir)
|
||||
sys.exit(1)
|
||||
|
||||
# -- PDF handling
|
||||
newpdf = opj(pubdir, stem, stem + '.pdf')
|
||||
oldpdf = opj(refcompat, doc + '.pdf')
|
||||
if not os.path.exists(oldpdf):
|
||||
oldpdf = opj(refcompat, stem, stem + '.pdf')
|
||||
assert os.path.exists(oldpdf)
|
||||
assert os.path.exists(newpdf)
|
||||
os.rename(oldpdf, oldpdf + '.' + str(int(time.time())))
|
||||
create_symlink(newpdf, oldpdf)
|
||||
|
||||
# -- HTML handling
|
||||
htmldir = opj(refcompat, doc, 'html')
|
||||
if not os.path.isdir(htmldir):
|
||||
htmldir, _ = os.path.split(htmldir)
|
||||
assert os.path.exists(htmldir)
|
||||
for fn in os.listdir(htmldir):
|
||||
if not fn.endswith('.html'):
|
||||
continue
|
||||
pubpath = newhtmlfilename(pubdir, stem, fn)
|
||||
url = pubpath.replace(pubdir, urlbase)
|
||||
fullname = opj(htmldir, fn)
|
||||
os.rename(fullname, fullname + '.' + str(int(time.time())))
|
||||
create_refresh_meta_equiv(fullname, url, stem, delay=2)
|
||||
|
||||
|
||||
def main(fin, fout, argv):
|
||||
me = os.path.basename(sys.argv[0])
|
||||
usage = "usage: %s <refpath> <refcompat> <pubdir> <urlbase>" % (me,)
|
||||
if not validate_args(argv):
|
||||
return usage
|
||||
refpath, refcompat, pubdir, urlbase = argv
|
||||
stems = collect_published_stems(pubdir)
|
||||
refs(stems, refpath, refcompat, pubdir, urlbase)
|
||||
return os.EX_OK
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
sys.exit(main(sys.stdin, sys.stdout, sys.argv[1:]))
|
||||
|
||||
# -- end of file
|
||||
|
|
@ -0,0 +1,21 @@
|
|||
#! /bin/bash
|
||||
|
||||
set -e
|
||||
set -x
|
||||
|
||||
SELFNAME="$( readlink --canonicalize ${0})"
|
||||
ME="${SELFNAME##*/}" # -- basename
|
||||
HERE="${SELFNAME%/*}" # -- dirname
|
||||
|
||||
{
|
||||
exec 2>&1;
|
||||
|
||||
bash $HERE/migration-preparation.sh;
|
||||
|
||||
bash $HERE/migration-helper.sh;
|
||||
|
||||
bash $HERE/golive.sh;
|
||||
|
||||
} | tee logfile-$( date +%F ).log
|
||||
|
||||
# -- end of file
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,882 @@
|
|||
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
|
||||
<article>
|
||||
|
||||
<artheader>
|
||||
<title>BTinternet pppd mini-HOWTO</title>
|
||||
|
||||
<author>
|
||||
<firstname>Matt</firstname>
|
||||
<surname>Wright</surname>
|
||||
<affiliation>
|
||||
<orgname><ulink url="http://www.consultmatt.co.uk">Matt Wright Consulting</ulink></orgname>
|
||||
<address>
|
||||
<email>matt@consultmatt.co.uk</email>
|
||||
</address>
|
||||
</affiliation>
|
||||
</author>
|
||||
|
||||
<othercredit role="converter">
|
||||
<firstname>Greg</firstname>
|
||||
<surname>Ferguson</surname>
|
||||
<contrib>Converted the mini-HOWTO from HTML to Docbook 3.1 (SGML).</contrib>
|
||||
</othercredit>
|
||||
|
||||
<pubdate>2002-03-26</pubdate>
|
||||
|
||||
<revhistory>
|
||||
<revision>
|
||||
<revnumber>v0.29</revnumber>
|
||||
<date>2002-03-26</date>
|
||||
<authorinitials>mww</authorinitials>
|
||||
<revremark>
|
||||
Added a small bit of first-hand tech support about
|
||||
cross-talk. Thanks goto Bill Staehle once again for typing,
|
||||
technical and grammar points.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v0.28</revnumber>
|
||||
<date>2002-01-17</date>
|
||||
<authorinitials>mww</authorinitials>
|
||||
<revremark>
|
||||
New information about PPPoATM involving kernels and
|
||||
distibutions.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v0.27</revnumber>
|
||||
<date>2001-12-20</date>
|
||||
<authorinitials>mww</authorinitials>
|
||||
<revremark>
|
||||
Minor technical problems highlighted by Robert Smith.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v0.26</revnumber>
|
||||
<date>2001-11-21</date>
|
||||
<authorinitials>mww</authorinitials>
|
||||
<revremark>
|
||||
Added a point about the Kernel HOWTO.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v0.25</revnumber>
|
||||
<date>2001-11-17</date>
|
||||
<authorinitials>mww</authorinitials>
|
||||
<revremark>
|
||||
Added a troubleshooting answer about "_mmx_memcpy". Other minor updates as well.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v0.24</revnumber>
|
||||
<date>2001-11-09</date>
|
||||
<authorinitials>mww</authorinitials>
|
||||
<revremark>
|
||||
Technical detail with the chatscript timeout (and found a spelling mistake or two!). Thanks again to Bill Staehle.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v0.23</revnumber>
|
||||
<date>2001-11-07</date>
|
||||
<authorinitials>mww</authorinitials>
|
||||
<revremark>
|
||||
Changed the Chatscript dialing method, thanks go to TonyC from btinternet.linux newsgroup.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v0.22</revnumber>
|
||||
<date>2001-11-06</date>
|
||||
<authorinitials>mww</authorinitials>
|
||||
<revremark>
|
||||
Changed a couple more little botches. Thanks again go to Bill Staehle.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v0.21</revnumber>
|
||||
<date>2001-11-03</date>
|
||||
<authorinitials>mww</authorinitials>
|
||||
<revremark>
|
||||
Changed discrepancies reported by Bill Staehle.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v0.20</revnumber>
|
||||
<date>2001-11-01</date>
|
||||
<authorinitials>mww</authorinitials>
|
||||
<revremark>
|
||||
Added Alcatel Speedtouch Information.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v0.19</revnumber>
|
||||
<date>2001-10-31</date>
|
||||
<authorinitials>mww</authorinitials>
|
||||
<revremark>
|
||||
Initial public release.
|
||||
</revremark>
|
||||
</revision>
|
||||
</revhistory>
|
||||
|
||||
<abstract>
|
||||
<para>
|
||||
This document describes how to setup a modem pppd link to
|
||||
Btinternet in the UK.
|
||||
</para>
|
||||
</abstract>
|
||||
|
||||
</artheader>
|
||||
|
||||
<sect1 id="intro">
|
||||
<title>Introduction</title>
|
||||
<para>
|
||||
This HOWTO exists because a mate of mine needed to easily set up an
|
||||
Internet connection to BTinternet and here is a quick and concise way
|
||||
to get a running PPPd to Btinternet. This HOWTO also briefly covers
|
||||
Howto setup basic IP Masquerading to allow connection sharing.
|
||||
</para>
|
||||
|
||||
<sect2 id="copyright">
|
||||
<title>Copyright and License</title>
|
||||
<para>
|
||||
This document is Copyright 2001 by Matt Wright. 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 no Invariant
|
||||
Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A
|
||||
copy of the license is available at
|
||||
<ulink url="http://www.gnu.org/copyleft/fdl.html">http://www.gnu.org/copyleft/fdl.html</ulink>
|
||||
</para>
|
||||
|
||||
<para>Send feedback to
|
||||
<ulink url="mailto:matt@consultmatt.co.uk"><citetitle>matt@consultmatt.co.uk</citetitle></ulink>.
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2 id="mailing">
|
||||
<title>Mailing Lists</title>
|
||||
|
||||
<para>Please note: There is a mailing list available for this howto. If you wish to join please email <email>majordomo@consultmatt.co.uk</email> with the body:</para>
|
||||
|
||||
<para><filename>subscribe bti-howto</filename></para>
|
||||
|
||||
<para>This will then be followed up by the mailing list bot and subsequent emails should arrive confirming your request. The list is intended to be for annoucing changes to this HOWTO and also to dicuss the finer points of getting pppd to work on BTinternet.</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2 id="author">
|
||||
<title>About the author</title>
|
||||
|
||||
<para> My name is Matt Wright. I'm 16 year-old student in Blackburn,
|
||||
Lancashire. I'm a freelance Linux consultant. I am the proud owner of
|
||||
a Duron 950Mhz (all I could easily afford) with 256MB SDRAM, Voodoo 4
|
||||
Video Card, ATI All-in-Wonder Pro Video Card. I also have a 266Mhz Cyrix
|
||||
that runs my USB ADSL connection, of which if you are reading this from
|
||||
<ulink url="http://www.consultmatt.co.uk">http://www.consultmatt.co.uk</ulink>
|
||||
you will be using. </para>
|
||||
|
||||
<para>
|
||||
You can find me at <ulink url="http://www.consultmatt.co.uk">www.consultmatt.co.uk</ulink>. Or at <ulink url="mailto:matt@consultmatt.co.uk">matt@consultmatt.co.uk</ulink>.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="greetz">
|
||||
<title>Acknowledgements</title>
|
||||
<para>A major thanks of gratitude to the guys at Linuxdoc in particular Greg Ferguson and David Merrill for help with getting this into trusty SGML. Also to Rob Smith the guy behind me writing this :) (As he couldn't sort his own Linux box out :P). A great vote of thanks to Bill Staehle for his input in ironing out some major flaws. Also a thank you goes to TonyC at btinternet.linux and the rest of that newsgroup for originally getting me on my feet with BTi. Finally and most importantly my thanks goto my Lord and Saviour Jesus Christ, without whom I'd be lost.</para>
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1 id="req">
|
||||
<title>Requirements</title>
|
||||
<para>
|
||||
The following is needed to use this HOWTO:
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>A working modem, external or internal hardware modems are the easiest to get working, see <ulink url="http://www.linuxdoc.org/HOWTO/Modem-HOWTO.html">Modem-HOWTO</ulink>. If you have a WinModem then see <ulink url="http://www.linuxdoc.org/HOWTO/Winmodems-and-Linux-HOWTO.html">Winmodems and Linux HOWTO</ulink></para></listitem>
|
||||
|
||||
<listitem><para>An account with Btinternet, this HOWTO covers
|
||||
BTi Surftime and Anytime</para></listitem>
|
||||
|
||||
<listitem><para>Some basic understanding of the Linux OS and
|
||||
its layout</para></listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1 id="surf">
|
||||
<title>Surftime</title>
|
||||
|
||||
<sect2>
|
||||
<title>PPPd Setup</title>
|
||||
|
||||
<para> Right, to start off you will need a working installation of
|
||||
PPPd, I know from experience that Mandrake 8.0 that sometime is
|
||||
doesn't install pppd so check its installed first. Once it is it
|
||||
usually resides in <filename>/usr/sbin/pppd</filename> check that any
|
||||
users you want to access it have setuid access.
|
||||
</para>
|
||||
<para>Note: Setuid allows pppd to run as-if root allowing non-superusers to run pppd without less problems. To do this use the command <command>chmod 4750 /usr/sbin/pppd</command>. Beware: Some distributions have a watchdog program that will change the pppd permissions back to normal. I have not tested this but on RedHat derived systems with Linuxconf installed then removing the <filename>/usr/lib/linuxconf/redhat/perm/ppp</filename> should stop this happening.</para>
|
||||
</sect2>
|
||||
|
||||
|
||||
<sect2>
|
||||
<title>Chatscript (Dialup)</title>
|
||||
|
||||
<para> The Chatscript is a text file, usually residing in
|
||||
<filename>/etc/ppp</filename> that contains the commands passed to
|
||||
the modem to make it dial to BTi. If you want to compare this to DUN
|
||||
in Windows then this is the phone number and init commands. </para>
|
||||
|
||||
<para> Below is the chatscript used to dial BTi, I've now opted for putting the \T metacharacter in the script. The means when we run <command>chat</command>, inside the pppd command, we can use a <filename>-T</filename> parameter and supply the needed telephone number.</para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
"" "ATZ"
|
||||
|
||||
# The next two lines should be left commented out until
|
||||
# the script works.
|
||||
|
||||
# "OK" "ATL0"
|
||||
# "OK" "ATM0"
|
||||
|
||||
SAY "Dialing modem...\n"
|
||||
"OK" "ATDT \T"
|
||||
ABORT BUSY
|
||||
ABORT "NO CARRIER"
|
||||
TIMEOUT 60
|
||||
CONNECT \c
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para> This script will dial BTi providing you put in the \T so we can added the telephone number later. I suggest saving the chatscript as something like <filename>/etc/ppp/chatscript</filename> Once you've saved it we can move onto setting up BTi's CHAP authentication.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
|
||||
<sect2>
|
||||
<title>Authentication</title>
|
||||
|
||||
<para> With PPP dialup's the most widely used authentication method,
|
||||
apparently, is PAP (Password Authentication Protocol). However, just
|
||||
to be a pain in the backside BTi use CHAP (Challenge Handshake
|
||||
Authentication Protocol). To be fair CHAP is a more secure authentication method than PAP but it's still a pain. Now PPPd does support this but not through
|
||||
nice easy to use Linuxconf dialogs. </para>
|
||||
|
||||
<para>In the
|
||||
<filename>/etc/ppp</filename> directory should be a
|
||||
<filename>chap-secrets</filename> that looks roughly like this when
|
||||
first installed: </para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
# Secrets for authentication using CHAP
|
||||
# client server secret IP addresses
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para> We can safely ignore the IP Address column but the others me
|
||||
must worry about. So fill in the gaps like this: </para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
# Secrets for authentication using CHAP
|
||||
# client server secret IP addresses
|
||||
"bloggs@btinternet.com" * "mypasswordhere"
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para> These two extra lines will try and authenticate ANY outgoing
|
||||
PPP connection that responds using CHAP using your BTi details. It
|
||||
goes without saying that you replace
|
||||
<emphasis>bloggs@btinternet.com</emphasis> and
|
||||
<emphasis>mypasswordhere</emphasis> with your details. Also, the second line is not strictly needed but I've found it helps sometimes.</para>
|
||||
|
||||
<para><emphasis role="strong">Note</emphasis>: If you're not using BTi at this point you can usually get away with having identical <filename>chap-secrets</filename> and <filename>pap-secrets</filename>. If you the same kind of pattern as above it should work.</para>
|
||||
|
||||
<para>I suggest that you do a "<command>chmod 600 /etc/ppp/*secrets</command>". It was pointed out to me that it stops pppd shouting about security.</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
|
||||
<sect2>
|
||||
<title>Setting your global options</title>
|
||||
|
||||
<para> In your <filename>/etc/ppp</filename> directory there is a
|
||||
file called <filename>options</filename>. If your open it with your
|
||||
favourite text editor you should see:</para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
lock
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para> And thats it, now we need to add some more settings in here so
|
||||
make it look like: </para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
lock
|
||||
usepeerdns
|
||||
defaultroute
|
||||
noipdefault
|
||||
noauth
|
||||
asyncmap 0
|
||||
crtscts
|
||||
modem
|
||||
115200
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para> Don't worry what they do, if you're interested look at the man
|
||||
page for pppd. As a passing note if you would like PPPd to redial
|
||||
dropped connections then add <emphasis>persist</emphasis> to the end
|
||||
of your options file. </para>
|
||||
</sect2>
|
||||
|
||||
|
||||
<sect2>
|
||||
<title>Testing your link</title>
|
||||
|
||||
<para> Now you've created your Chatscript there are only two steps
|
||||
left till you should be on the Internet. First is getting a working
|
||||
link and second is creating a couple of easy dialup scripts to help
|
||||
you. </para>
|
||||
|
||||
<para>
|
||||
To test your link try this command:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<command>pppd ttyS0 connect '/usr/sbin/chat -v -TPHONE_NUM_HERE -f /etc/ppp/chatscript' updetach debug name bloggs@btinternet.com</command></para>
|
||||
|
||||
<para> Now obviosuly if your testing at Daytiem rate add the Daytiem number where instead of <filename>PHONE_NUM_HERE</filename> and similar with Surftime.</para>
|
||||
<para> This will tell PPPd to dial the modem on ttyS0 (COM1) using the chatscript. The <option>updetach</option> tells PPPd to only fork away to the commandline after the connection is established and the <option>debug</option> will show all authentication commands onscreen (providing updetach it set) while it trys to connect. </para>
|
||||
|
||||
<para> If that connected then move onto the next section and we can
|
||||
make a set of scripts to allow easy dialing. </para>
|
||||
</sect2>
|
||||
|
||||
|
||||
<sect2>
|
||||
<title>Dialing scripts</title>
|
||||
|
||||
<para> Here I'll just set out a set of scripts that will let your
|
||||
dial BTi from a command line easily. The following should be
|
||||
self-explanatory, the italic filename is the filename to put the data
|
||||
into and the proceeding text the file contents: </para>
|
||||
|
||||
<para><command>/etc/ppp/peers/bt-surf</command></para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
ttyS0 connect '/usr/sbin/chat -v -TSURFTIME_NUMBER_HERE -f /etc/ppp/chatscript'
|
||||
updetach name bloggs@btinternet.com
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para><command>/etc/ppp/peers/bt-day</command></para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
ttyS0 connect '/usr/sbin/chat -v -TDAYTIME_NUMBER HERE -f /etc/ppp/chatscript'
|
||||
updetach name bloggs@btinternet.com
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para> Change any of the filenames to suit what you called them and
|
||||
the username. Do the same with this: </para>
|
||||
|
||||
<para><command>/usr/bin/internet</command></para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
#!/bin/bash
|
||||
# a script to dial BTi
|
||||
case "$1" in
|
||||
daytime)
|
||||
/usr/sbin/pppd call bt-day
|
||||
;;
|
||||
surftime)
|
||||
/usr/sbin/pppd call bt-surf
|
||||
;;
|
||||
off)
|
||||
killall pppd
|
||||
;;
|
||||
esac
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para> Once you've done that run this command at the command prompt:
|
||||
</para>
|
||||
|
||||
<para><command>chmod a+x /usr/bin/internet</command></para>
|
||||
|
||||
<para> Now you've done, simply type
|
||||
<command>internet daytime/surftime/off</command> and it
|
||||
will connect you to the internet. </para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1>
|
||||
<title>BTi Anytime</title>
|
||||
|
||||
<para> I'm sorry, for all you Anytime customers its really hard!
|
||||
NOT! Read all the instructions for Surftime above. They all apply in
|
||||
most places, the only things to watch out for is you obviously don't
|
||||
need any of the Surftime/daytime distinctions. So only have one
|
||||
peers file (using the correct phoen number) and one dialup option in your <filename>/usr/bin/internet</filename> file. (eg. dial and off)</para>
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1>
|
||||
<title>BTOpenworld Home 500 (Alcatel Speedtouch USB)</title>
|
||||
|
||||
<sect2>
|
||||
<title>About this section</title>
|
||||
|
||||
<para> There is rather a large amount of credit due here, to
|
||||
<ulink url="mailto:chris@black-sun.co.uk">Chris Jones</ulink> for writing the
|
||||
<ulink url="http://www.linuxdoc.org/HOWTO/DSL-HOWTO/speedtouchusb.html">Alcatel
|
||||
Speedtouch USB ASDL Modem mini-HOWTO</ulink> that is now part of the
|
||||
<ulink url="http://www.linuxdoc.org/HOWTO/DSL-HOWTO/">DSL HOWTO</ulink>.
|
||||
This helped me a great deal when trying to get my Speedtouch to work. </para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Warning</title>
|
||||
|
||||
<para>At home I use Linux Mandrake, although the version of the kernel I had was patched with the ATM kernel source I did end up patching a different kernel source to get it working. Please, please inspect your kernel source to see if you have the PPPoATM source patched against your kernel. To do this go into you kernel source directory, usually <filename>/usr/src/linux</filename> and do a <command>make menuconfig</command>. In the Network Device Support section check for:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>Network device support->PPP over ATM</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>If it does exist then make sure it is present it you current kernel and you can skim-read the "Patching you kernel" section to make sure you have the correc toptions compiled in and then carry on.</para>
|
||||
|
||||
<para>This was just a minor warning as I orginially had a kernel patched with PPPoATM and without realising managed to trash my kernel tree by trying to force the patch onto it.</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Distribution Specific Information</title>
|
||||
|
||||
<para>I have had reports about different distros that have varying
|
||||
PPPoATM support already builtin to the kernel:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>Mandrake 8.0: The default 2.4.3 kernel already has the
|
||||
PPPoATM patch applied, I cannot remember if it compiled in but ignore
|
||||
steps refering the "Patching the Kernel" below. PS: You still need to
|
||||
configure the kernel.</para></listitem>
|
||||
<listitem><para>Mandrake 8.1: Mandrake 8.1 supports the Speedtouch
|
||||
automatically, I have no had first hand experience but from what I can
|
||||
gather you simply have to download the Alcatel binaries and then use
|
||||
DrakNet to sort it out.</para></listitem>
|
||||
<listitem><para>Debian: I have had reports that the standard Debian
|
||||
installtion does not include libpam, this must be installed for the
|
||||
PPPoATM plugin modules to work.</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>NOTE: From roughly kernel 2.4.16 the PPPoATM patch is included in
|
||||
Linus' main source tree. Therefore you can miss out patching the kernel
|
||||
and just configure it.</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Requirements</title>
|
||||
|
||||
<para> To get your Speedtouch USB working in Linux you have a fairly
|
||||
heavyweight task ahead of you, but hey, if I could do it so can you!
|
||||
This is what you'll need to get it working: </para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>You must have the kernel source installed and
|
||||
know the procedure for installing and compiling a new kernel.
|
||||
If this is a problem then read the <ulink url="http://www.linuxdoc.org/HOWTO/Kernel-HOWTO.html">Kernel HOWTO</ulink>.</para></listitem>
|
||||
|
||||
<listitem><para>You must be running one of the following
|
||||
Kernels: 2.3.39, 2.4.0-test4, 2.4.1-pre7, 2.4.7, 2.4.8-pre5.
|
||||
This is because the PPPoATM patch for the kernel exists patched
|
||||
against specific kernels, some may work with similar kernel
|
||||
versions but I cannot vouch for that</para></listitem>
|
||||
|
||||
<listitem><para>You, obviously, need a USB controller of some
|
||||
description with at least one free plug. It also must be Linux
|
||||
compatible, nowadays this is most USB controllers that are
|
||||
UHCI/OHCI based. If you don't have one your local supplier
|
||||
would probably have a PCI USB Controller.</para></listitem>
|
||||
|
||||
<listitem><para>A heap-load of confidence with meddling with
|
||||
your config. eg: kernel recompiling, program
|
||||
installation...</para></listitem>
|
||||
</itemizedlist>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Software Downloads</title>
|
||||
|
||||
<para> To get the Speedtouch working under Linux you will need some
|
||||
software and kernel patches found below: </para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>The kernel patch for your kernel. They can be found at <ulink url="http://www.kernel.org/pub/linux/kernel/people/axboe/PPPoATM/">http://www.kernel.org/pub/linux/kernel/people/axboe/PPPoATM/</ulink>. Please note not all the kernels have patches.</para></listitem>
|
||||
|
||||
<listitem><para>The latest SpeedTouch driver from <ulink url="http://sourceforge.net/project/showfiles.php?group_id=3581">http://sourceforge.net/project/showfiles.php?group_id=3581</ulink></para></listitem>
|
||||
|
||||
<listitem><para>The latest SARlib library from <ulink url="http://sourceforge.net/project/showfiles.php?group_id=22221">http://sourceforge.net/project/showfiles.php?group_id=22221</ulink></para></listitem>
|
||||
|
||||
<listitem><para>The Alcatel speed management software. You can get it from <ulink url="http://www.alcatel.com/consumer/dsl/dvrreg_lx.htm">http://www.alcatel.com/consumer/dsl/dvrreg_lx.htm</ulink>. I can't distribute this because of Alcatel's licensing scheme so get it from them.</para></listitem>
|
||||
|
||||
<listitem><para>Some description of PPPoATM aware PPPd binary:</para>
|
||||
<itemizedlist>
|
||||
<listitem><para>Red Hat 7 RPM (glibc 2.2): <ulink url="http://sourceforge.net/project/showfiles.php?group_id=23818">http://sourceforge.net/project/showfiles.php?group_id=23818</ulink></para></listitem>
|
||||
<listitem><para>Debian (.deb): <ulink url="http://sourceforge.net/project/showfiles.php?group_id=23818">http://sourceforge.net/project/showfiles.php?group_id=23818</ulink></para></listitem>
|
||||
<listitem><para>Tarball: <ulink url="http://sourceforge.net/project/showfiles.php?group_id=23818">http://sourceforge.net/project/showfiles.php?group_id=23818</ulink></para></listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
|
||||
<listitem><para>The Linux Hotplug software from <ulink url="http://linux-hotplug.sourceforge.net">http://linux-hotplug.sourceforge.net</ulink>. Get it installed as per their instructions. It seemed simple enough so I won't cover it here</para></listitem>
|
||||
</itemizedlist>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Patching your kernel</title>
|
||||
|
||||
<para> Once you have the PPPoATM kernel patch (this assumes you use
|
||||
the patch against kernel 2.4.7) you need to make sure you have a
|
||||
working 2.4.7 kernel tree, next unzip the PPPoATM patch by doing:
|
||||
</para>
|
||||
|
||||
<para>NOTE: From rougly kernel 2.4.16 (I haven't tested to see hwo far
|
||||
back it goes) the PPPoATM patch is included in Linus' main kernel tree,
|
||||
therefore you may skip the patching below and resume ready to configure
|
||||
the kernel.</para>
|
||||
|
||||
<para><command>gzip -d pppoatm-2.zip</command></para>
|
||||
|
||||
<para> Next we will need to test-patch the kernel using the following
|
||||
commands: </para>
|
||||
|
||||
<para><command>patch -p1 -s -E --dry-run < /point/to/pppoatm-2</command></para>
|
||||
|
||||
<para> If that ran without failure then patch the kernel by removing
|
||||
the <option>--dry-run</option> as such: </para>
|
||||
|
||||
<para><command>patch -p1 -s -E < /point/to/pppoatm-2</command></para>
|
||||
|
||||
<para> That should have patched the kernel good-and-proper so we can
|
||||
go ahead and configure it, make sure the following options are
|
||||
selected along with your personal build options: </para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>Code maturity levels->Prompt for development and/or incomplete code/drivers</para></listitem>
|
||||
<listitem><para>Networking options->Asynchronous Transfer Mode (ATM)</para></listitem>
|
||||
<listitem><para>Network device support->PPP (point-to-point protocol) support</para></listitem>
|
||||
<listitem><para>Network device support->PPP support for async serial ports</para></listitem>
|
||||
<listitem><para>Network device support->PPP Deflate compression</para></listitem>
|
||||
<listitem><para>Network device support->PPP BSD-Compress compression</para></listitem>
|
||||
<listitem><para>Network device support->PPP over ATM</para></listitem>
|
||||
<listitem><para>USB support->Support for USB</para></listitem>
|
||||
<listitem><para>USB support->Preliminary USB device filesystem</para>
|
||||
<para>You have to make a choice here, if your USB controller is
|
||||
UHCI based then select:</para>
|
||||
<para>USB support->UHCI (Intel, PIIX4, VIA, ...) support</para>
|
||||
<para>Alternatively choose:</para>
|
||||
<para>USB Support->OHCI (Compaq, iMacs, OPTi, SiS, ALi, ...) support</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para> You could select any of these as modules or compiled-in but as
|
||||
I followed Chris Jones' HOWTO I compiled the all but UHCI/OHCI as
|
||||
compiled-in code. Save the kernel config and compile the kernel and
|
||||
modules as you normally do. </para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Kernel Drivers and Software</title>
|
||||
|
||||
<para> Now that the kernel will support using PPPoATM we can start
|
||||
compiling the bits to run the modem. Well start with the Kernel mode
|
||||
driver; first decompress the SARlib sources to a build directory.
|
||||
(Personally I build all my non-kernel sources
|
||||
in <filename>~/sources</filename>) and do a
|
||||
<command>make</command> on it. There is no need to do
|
||||
a <command>make install</command> with this library.</para>
|
||||
|
||||
<para> Next return to your source root and decompress your Speedtouch
|
||||
drivers (from Sourceforge not Alcatel!), go in there and do a
|
||||
<command>make</command>, and then a <command>make install</command>.</para>
|
||||
|
||||
<para> <emphasis role="strong">Note:</emphasis> If you get an "Error
|
||||
1" then check the <filename>Makefile</filename> for a line starting
|
||||
<option>SARLIB:=</option> and check it points to the right directory, the
|
||||
one where you just compiled SARlib. </para>
|
||||
|
||||
<para> Next install the Hotplug software and make sure it works. Once
|
||||
you've done that decompress Alcatel's binary management software and
|
||||
do a <command>make</command> on that. Then do a <command>make
|
||||
install</command>, the clever bit here is their installation
|
||||
registers the Speedtouch kernel driver and their binary to be run
|
||||
when the USB device is "hotplugged" (or coldplugged) into the system.
|
||||
<emphasis>Kiss goodbye to the hours of trying to writing modules
|
||||
loading scripts that always fail.</emphasis> </para>
|
||||
|
||||
<para> Next install the new PPPoATM aware PPPd program, I had no luck
|
||||
getting it compile from source on my machine so I used the RPM. Sorry
|
||||
you're on your own there! </para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>PPPd Configuration</title>
|
||||
|
||||
<para> <emphasis role="strong">Warning:</emphasis> The action will
|
||||
remove all the default settings for any previous PPPd connection.
|
||||
(Not that you want them now you've got shiny new ADSL ;P) </para>
|
||||
|
||||
<para> In the <filename>/etc/ppp</filename> directory there is a file called
|
||||
<filename>options</filename> in that file put the following: </para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
lock
|
||||
defaultroute
|
||||
noipdefault
|
||||
noauth
|
||||
passive
|
||||
asyncmap 0
|
||||
name bloggs@hg5.btinternet.com
|
||||
user bloggs@hg5.btinternet.com
|
||||
plugin /usr/lib/pppd/plugins/pppoatm.so
|
||||
0.38
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para> Make sure of the following things: </para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>That you replace both name
|
||||
<emphasis role="strong">and</emphasis> user variables with your
|
||||
username.</para></listitem>
|
||||
|
||||
<listitem><para>That you get the correct VPI/VCI ATM pair,
|
||||
these are in the windows information software, from BTi my
|
||||
VPI:0 and VCI:38 so I use <option>0.38</option>. Make sure
|
||||
you get this right or it <emphasis role="strong">will not
|
||||
work</emphasis>.</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para> Next in your <filename>/etc/ppp/chap-secrets</filename> put:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
# Secrets for authentication using CHAP
|
||||
# client server secret IP addresses
|
||||
"bloggs@hg5.btinternet.com" * "mypasswordhere"
|
||||
</screen>
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Testing your link</title>
|
||||
|
||||
<para> Next thing to do is get the link up and test it. If you've got
|
||||
a nice distro like Mandrake you should find it will auto-init your
|
||||
USB drivers and filesystem, if not then the following can be used:
|
||||
</para>
|
||||
|
||||
<para><command>/sbin/modprobe usb-uhci</command></para>
|
||||
<para><command>mount none /proc/bus/usb -tusbdevfs</command></para>
|
||||
|
||||
<para> Next load the Speedtouch driver by doing:
|
||||
<command>/sbin/modprobe speedtch</command>. Next use the speedmgmt
|
||||
program to get the modem init'ed: <command>/usr/sbin/mgmt</command>.
|
||||
After a while of the lights flashing on the modem the main console
|
||||
(and/or the syslog) should report: </para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
Speedmgmt[2074]: Modem initialised at 576 kbit/s downstream and 288 kbit/s upstream
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para> Once the modem has been init'ed now make sure the PPPoATM
|
||||
module is loaded by doing: </para>
|
||||
|
||||
<para><command>modprobe pppoatm</command></para>
|
||||
|
||||
<para> Now start the PPP link by typing <command>pppd</command> You
|
||||
should see something similar to this: </para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
Oct 28 14:01:25 ds9 pppd: PPPoATM plugin_init
|
||||
Oct 28 14:01:25 ds9 pppd: PPPoATM setdevname_pppoatm
|
||||
Oct 28 14:01:25 ds9 pppd: PPPoATM setdevname_pppoatm - SUCCESS
|
||||
Oct 28 14:01:26 ds9 pppd: Using interface ppp0
|
||||
Oct 28 14:01:26 ds9 pppd: Connect: ppp0 <--> 0.38
|
||||
Oct 28 14:01:28 ds9 pppd: local IP address 255.255.255.255
|
||||
Oct 28 14:01:28 ds9 pppd: remote IP address 255.255.255.255
|
||||
Oct 28 14:01:28 ds9 pppd: primary DNS address 213.120.62.100
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para> Once that's done you're in luck, now just configure the pppd
|
||||
to autodial at startup (beyond the scope of this HOWTO, sorry!).
|
||||
Hopefully HotPlug will get your device up and going before pppd needs
|
||||
it! :). </para>
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1>
|
||||
<title>Simple IP Masquerading</title>
|
||||
|
||||
<para> To allow sharing of your internet conenction you can eitehr
|
||||
use a proxy server or IP Masquerading. I'll cover IP Masquerding as
|
||||
it's simple to set up on the other client machines. I use a 2.4.x
|
||||
generation kernel and in effect I use IPTables. If you use a 2.2.x or
|
||||
2.0.x kernel then you need the
|
||||
<ulink url="http://www.linuxdoc.org/HOWTO/IP-Masquerade-HOWTO.html">IP
|
||||
Masquerading HOWTO</ulink>. </para>
|
||||
|
||||
<para> This part of the HOWTO assumes that your Netfilter software is
|
||||
modularised, if it isnt then no big deal, either ignore the
|
||||
<option>modprobe</option> lines or recompile your kernel. </para>
|
||||
|
||||
|
||||
<para> Simple now, just run the commands: </para>
|
||||
|
||||
<para><command>modprobe iptable_nat</command></para>
|
||||
<para><command>iptables -t nat -F POSTROUTING</command></para>
|
||||
<para><command>iptables -t nat -A POSTROUTING -o ppp0 -s 10.0.0.0/16 -j MASQUERADE</command></para>
|
||||
<para><command>echo 1 > /proc/sys/net/ipv4/ip_forward</command></para>
|
||||
<para><emphasis role="strong">Note:</emphasis> The space between 1 and > is vital. It seems not to activate the IP Forwarding if the space is not there.</para>
|
||||
|
||||
<para> Change the <option>ppp0</option> and/or the
|
||||
<option>10.0.0.0/16</option> for your relevant network settings and
|
||||
put that file either before the <option>case "$1" in</option> in the
|
||||
<filename>internet</filename> file or somewhere in your startup.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1>
|
||||
<title>Troubleshooting</title>
|
||||
|
||||
<sect2>
|
||||
<title>Help! Lynx gives unable to access document</title>
|
||||
|
||||
<para><emphasis role="strong">Problem:</emphasis>
|
||||
Lynx is unable to access document or ping gives "No
|
||||
route to host" but the link is stable! </para>
|
||||
|
||||
<para> <emphasis role="strong">Solution:</emphasis> Have a look at
|
||||
the output of <command>route -n</command> you should see a
|
||||
refenence specifing a gateway of either your Remote PPP IP
|
||||
and using the adapter/dev of ppp0. If not here is how to fix it. In
|
||||
your <filename>/etc/ppp/ip-up</filename> file above
|
||||
<option>exit 0</option> on the last line type: </para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
route del default
|
||||
route add default gw $4 $1
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para> Save the file and redial. The problem should be solved.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>My kernel < 2.4.2 crashes using the Alcatel driver</title>
|
||||
|
||||
<para><emphasis role="strong">Problem:</emphasis>
|
||||
Your kernel below 2.4.2 crashes using the Alcatel driver.
|
||||
</para>
|
||||
|
||||
<para> <emphasis role="strong">Solution:</emphasis>
|
||||
You're probably using a kernel compiled with SMP support either don't
|
||||
use SMP or try here:
|
||||
<ulink url="http://sourceforge.net/project/showfiles.php?group_id=23818">http://sourceforge.net/project/showfiles.php?group_id=23818</ulink>
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>PPPd crashes when it loads the PPPoATM module</title>
|
||||
|
||||
<para><emphasis role="strong">Problem:</emphasis>
|
||||
When PPPd attempts to access the ATM device it crashes.
|
||||
</para>
|
||||
|
||||
<para> <emphasis role="strong">Solution:</emphasis> The kernel was
|
||||
probably compiled on a different type of processor. I tried to get
|
||||
the kernel compiled quicker by compiling the kernel on my 950Mhz
|
||||
Duron, even with the processor type to suit the target 266Mhz Cyrix
|
||||
the ATM module crashes. So dont take short cuts and compile on the
|
||||
target processor. </para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>insmod speedtch.o gives: "Unresolved symbol: _mmx_memcpy"</title>
|
||||
<para><emphasis role="strong">Problem:</emphasis>
|
||||
When you have compiled the Speedtouch Kernel driver (speedtch.o) trying to insmod/modprobe returns: "Unresolved symbol: _mmx_memcpy" or similar.
|
||||
</para>
|
||||
|
||||
<para><emphasis role="strong">Solution:</emphasis>
|
||||
Right, I haven't got a concrete answer here but I couldn't find it anywhere on the internet so here goes. I found this error come up when I recompiled my kernel once. It did it the first time but I forgot how to fix it. A combination of things fixed it for me:
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>Configured the kernel module support to ignore kernel version checking</para></listitem>
|
||||
<listitem><para>Recompiled SARlib (this is what ultimately fixed it) before recompiling speedtch.o</para></listitem>
|
||||
<listitem><para>Recompiled speedtch.o and reinstalled. Et voila!</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
As I said I can't be sure about this one but it worked for me.
|
||||
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>There are strange noises on the telephone line when I pick up the
|
||||
phone.</title>
|
||||
|
||||
<para><emphasis role="strong">Problem:</emphasis>
|
||||
When you pick up the phone there are strange noises present, more over
|
||||
the use of the phone line causes the internet to disconnect.</para>
|
||||
|
||||
<para><emphasis role="strong">Solution:</emphasis>
|
||||
You seem to have something which I think is called cross-talk. The
|
||||
ADSL modem works by sending data down the unused frequencies of your
|
||||
copper phone line. If the hardware is set up so the ADSL and phone
|
||||
ranges overlap the two can "hear" each other. The best advice is to
|
||||
Ring BTO Customer Support and they should be able to help.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1>
|
||||
<title>Further Reading</title>
|
||||
|
||||
<para>
|
||||
For further reading on related topics see this list:
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>The <ulink url="http://www.linuxdoc.org/HOWTO/PPP-HOWTO/index.html">PPP-HOWTO</ulink></para></listitem>
|
||||
<listitem><para>The <ulink url="http://www.linuxdoc.org/HOWTO/IP-Masquerade-HOWTO.html">IP Masquerading HOWTO</ulink></para></listitem>
|
||||
<listitem><para>The <ulink url="http://www.linuxdoc.org/HOWTO/DSL-HOWTO/index.html">DSL HOWTO</ulink></para></listitem>
|
||||
<listitem><para>The <ulink url="http://www.linuxdoc.org/HOWTO/Modem-HOWTO.html">Modem-HOWTO</ulink>.</para></listitem>
|
||||
<listitem><para>The <ulink url="http://www.linuxdoc.org/HOWTO/Winmodems-and-Linux-HOWTO.html">Winmodems and Linux HOWTO</ulink></para></listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
|
||||
</article>
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,260 @@
|
|||
<?xml version="1.0"?>
|
||||
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://docbook.org/xml/4.2/docbookx.dtd"
|
||||
>
|
||||
<article id="spm">
|
||||
<articleinfo><title>Complete System Performance Monitor HOWTO</title>
|
||||
<abstract>
|
||||
<para>This HOWTO provides an overview of the Complete System Performance Monitor, including a description of the product and installation and configuration information.</para>
|
||||
</abstract>
|
||||
<author>
|
||||
<firstname>Chris</firstname>
|
||||
<surname>Lorenz</surname>
|
||||
<affiliation>
|
||||
<address><email>lorenzc@us.ibm.com</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
<pubdate>2003-06-10</pubdate>
|
||||
<revhistory>
|
||||
<revision>
|
||||
<revnumber>2.0</revnumber>
|
||||
<date>2003-06-10</date>
|
||||
<authorinitials>CL</authorinitials>
|
||||
</revision>
|
||||
</revhistory>
|
||||
</articleinfo>
|
||||
<sect1 id="copy"><title>Copyright and legal notice</title>
|
||||
<para>Copyright © 2003 IBM Corporation. All
|
||||
rights reserved.
|
||||
</para>
|
||||
<para>This document is provided "AS IS," with no
|
||||
express or implied warranties. Use the information in
|
||||
this document at your own risk.
|
||||
</para>
|
||||
<para>Linux is a registered trademark of Linus Torvalds. Other company, product, and service
|
||||
names may be trademarks or service marks of others.
|
||||
</para>
|
||||
<para>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 no Invariant Sections, no Front-Cover text, and no Back-Cover text. A copy of the license can be found at <ulink url="http://www.gnu.org/licenses/fdl.txt">http://www.gnu.org/licenses/fdl.txt</ulink>.</para>
|
||||
</sect1>
|
||||
<sect1><title>What Is the Complete System Performance Monitor?</title>
|
||||
<para>The Complete System Performance Monitor (CSPM), written by Don Dupuis of Compaq Computer Corporation, is a graphical tool that monitors a Linux® system's CPU, memory, storage, network, and IRQ utilization. CSPM gathers all the data automatically and then generates histogram displays of system usage. </para></sect1>
|
||||
|
||||
<sect1><title>Requirements</title>
|
||||
<para>CSPM V1.0 and later require the following:</para>
|
||||
<itemizedlist><listitem><para>Red Hat Linux 7.2 or later, Mandrake 8.2 or later, or any Linux
|
||||
kernel that has Stephen Tweedie's <command>sar</command> or <command>sysstat</command> patch applied (such as 2.4.20).</para></listitem>
|
||||
<listitem><para>The Trolltech Qt 3.0 or later C++ application development environment, which is available for download from Trolltech for free.</para></listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
|
||||
<sect1><title>Installing CSPM and its requirements</title>
|
||||
<para>This section describes how to acquire the Qt application development environment and install CSPM.</para>
|
||||
<sect2><title>Installing Qt 3.0 or later</title>
|
||||
|
||||
<para>Qt 3.0 or later must be installed on the system before you install CSPM.
|
||||
Follow these steps to acquire and configure Qt:
|
||||
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>Download the Qt X/11 Free Edition from <ulink url="www.trolltech.com">http://www.trolltech.com</ulink> for the latest version of Qt. </para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Follow Trolltech's instructions for installing Qt. </para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Run .<command>/configure</command> with the <constant>-thread</constant> switch to the configure
|
||||
program so that Qt is installed to run in multithreaded mode.</para>
|
||||
<programlisting># ./configure -thread</programlisting>
|
||||
</listitem>
|
||||
<listitem><para>Be sure to export the variables QTDIR and LD_LIBRARY_PATH, as
|
||||
described in the Qt installation instructions that are downloaded with the software.</para>
|
||||
</listitem></orderedlist>
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2><title>Installing CSPM</title>
|
||||
<para>The following sections describe how to download and install CSPM.
|
||||
These steps must be run by the root user.
|
||||
The installation process creates a directory called <filename>spm</filename> and places all the files in that directory.
|
||||
|
||||
</para>
|
||||
<sect3><title>Installing from rpm</title>
|
||||
<para>Follow these steps to install CSPM from the rpm file:</para>
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>Download the CSPM rpm file from SourceForge at <ulink url="http://sourceforge.net/projects.cspm">http://sourceforge.net/projects/cspm</ulink>. The program name
|
||||
for CSPM is <filename>spm2</filename>. </para>
|
||||
</listitem>
|
||||
<listitem><para>Install the software:</para>
|
||||
<programlisting># rpm -ihv --nodeps spm2-1.0-1.586.rpm</programlisting>
|
||||
<para>The rpm creates the binary call <command>spm2</command> in the current directory.</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
|
||||
</sect3>
|
||||
<sect3><title>Installing from tar</title>
|
||||
<para>Follow these steps to install CSPM from the tar file:</para>
|
||||
<orderedlist>
|
||||
<listitem><para>Download the CSPM tar file from SourceForge at <ulink url="http://sourceforge.net/projects.cspm">http://sourceforge.net/projects/cspm</ulink>. The program name
|
||||
for CSPM is <filename>spm2</filename>. </para></listitem>
|
||||
|
||||
<listitem><para>Untar the <filename>spm2.tar.gz</filename> file:</para>
|
||||
<programlisting># tar xvzf spm2.tar.gz</programlisting></listitem>
|
||||
<listitem><para>Compile CSPM:</para>
|
||||
<programlisting># make all</programlisting>
|
||||
<para>The <command>make</command> command creates the binary call <command>spm2 </command>in the current directory.</para></listitem>
|
||||
</orderedlist>
|
||||
</sect3>
|
||||
</sect2>
|
||||
|
||||
<sect2><title>Starting the CSPM monitor</title>
|
||||
<para>The <filename>spm2</filename> program should be run by a user other than root so that any changes to
|
||||
the default preference settings can be changed.</para>
|
||||
<para>Enter the following command from the directory where CSPM is installed:</para>
|
||||
<para><programlisting># ./spm2</programlisting></para>
|
||||
<para>If a segmentation fault occurs when <command>spm2</command> is starting up, make sure that you have set the QTDIR and LD_LIBRARY_PATH variables, as described in the Qt installation instructions that are downloaded with the software.</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1><title>Modifying CSPM defaults</title>
|
||||
<para>By default, the number of "range bars" along the y-coordinate of each histogram
|
||||
is five. When there is no activity for a particular device, CSPM provides default values
|
||||
of 0, 0.2, 0.4, 0.6, and 0.8. Once activity begins on the device, CSPM sets the
|
||||
five values in equal increments from 0 to the peak data value collected in each
|
||||
collection interval. Sometimes the grid lines fall directly on the range bar numbers,
|
||||
making the numbers hard to read. You can either adjust the color of the grid lines,
|
||||
adjust the collection interval, or try to ignore the grid lines.
|
||||
</para>
|
||||
|
||||
<para>You can modify the default grid, sizing, and monitoring settings for each of the views from
|
||||
the <menuchoice><guimenu>Preferences</guimenu></menuchoice> pulldown. From the
|
||||
<menuchoice><guimenu>Preferences</guimenu></menuchoice> pulldown, you can select <guilabel>System</guilabel>,
|
||||
<guilabel>Tests</guilabel>, <guilabel>CPU</guilabel>, <guilabel>Memory</guilabel>, <guilabel>Network</guilabel>,
|
||||
<guilabel>Storage</guilabel> or <guilabel>IRQs</guilabel>. Once you select a particular item, you
|
||||
can view the <guilabel>Grid</guilabel>, <guilabel>Monitoring</guilabel>, or <guilabel>Sizing</guilabel> tab
|
||||
(if applicable) for that item.</para>
|
||||
<para>From the <guilabel>Grid</guilabel> tab you can change such things as:</para>
|
||||
|
||||
<itemizedlist><listitem><para>the color of the grid lines</para></listitem>
|
||||
<listitem><para>the distance (or time), in seconds, between intervals when data is collected (horizontal lines appear at each interval)</para></listitem>
|
||||
<listitem><para>the color of the various data bars (such as read, write, user, nice, and "sys")</para></listitem>
|
||||
<listitem><para>the number of horizontal range bars (default is 5)</para></listitem>
|
||||
<listitem><para>the size of the histogram titles</para></listitem></itemizedlist>
|
||||
|
||||
<para>From the <guilabel>Monitor</guilabel> tab you can change things such as:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>the height and width of the display boxes (in pixels)</para></listitem>
|
||||
<listitem><para>the colors of the display boxes</para></listitem>
|
||||
<listitem><para>the type of data to be monitored (IOs, data, reads and writes, sectors and blocks)</para></listitem></itemizedlist>
|
||||
|
||||
<para>From the <guilabel>Sizing</guilabel> tab you can change the minimum height and width of the
|
||||
display boxes (in pixels).</para>
|
||||
</sect1>
|
||||
<sect1><title>How CSPM displays data</title>
|
||||
<para>CSPM displays histograms that provide information about system usage.
|
||||
The program has 8 display tabs for the different types of system information CSPM
|
||||
collects. These tabs are:</para>
|
||||
<itemizedlist>
|
||||
<listitem><para><guilabel>System Overview</guilabel></para>
|
||||
</listitem>
|
||||
<listitem><para><guilabel>IRQs</guilabel></para>
|
||||
</listitem>
|
||||
<listitem><para><guilabel>CPU Utilization</guilabel></para>
|
||||
</listitem>
|
||||
<listitem><para><guilabel>Memory</guilabel></para>
|
||||
</listitem>
|
||||
<listitem><para><guilabel>Network</guilabel></para>
|
||||
</listitem>
|
||||
<listitem><para><guilabel>Storage</guilabel></para>
|
||||
</listitem>
|
||||
<listitem><para><guilabel>Tests</guilabel></para>
|
||||
</listitem>
|
||||
<listitem><para><guilabel>Test Summary</guilabel></para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>The key at the bottom of the histogram tables on each of the tabs tells how to interpret
|
||||
the various colors representing data in the tables.</para>
|
||||
<para>Use the horizontal and vertical scroll bars to view any histograms that do not
|
||||
fit on the initial screen.</para>
|
||||
|
||||
<sect2><title><guilabel>System Overview</guilabel> tab</title>
|
||||
<para>When CSPM starts up, the <guilabel>System Overview</guilabel> screen is displayed. The histograms
|
||||
on the <guilabel>System Overview</guilabel> screen show data for the total system, including CPU, memory,
|
||||
network, and storage usage. The following screenshot shows a sample view of a
|
||||
System Overview screen. </para>
|
||||
<para><graphic fileref="sysover.png"/></para>
|
||||
<para>Below each histogram is a key that describes the data that is represented. For example, in the
|
||||
CPU total histogram, the red line represents user CPU usage, the green line represents commands run with a modified scheduling priority (nice), and the blue line represents system CPU usage.</para>
|
||||
</sect2>
|
||||
|
||||
<sect2><title><guilabel>IRQs</guilabel> tab</title>
|
||||
|
||||
<para>When you click the <guilabel>IRQs</guilabel> tab, a histogram opens for each IRQ line that
|
||||
runs to an ISA slot
|
||||
on the system. The following screenshot shows a sample view of the IRQs screen.</para>
|
||||
<para><note><title>Note</title>
|
||||
<para>With Qt 3.0, the horizontal scroll bars on the Irqs tab does not work properly. This
|
||||
problem does not occur with Qt 3.1.</para></note></para>
|
||||
<para><graphic fileref="irqs.png"/></para>
|
||||
<para>The large blue number to the left of the histogram is the number of the IRQ.
|
||||
The
|
||||
red line on each histogram represents the number of IRQs per second utilitized by the device
|
||||
connected to the IRQ's ISA slot.</para>
|
||||
</sect2>
|
||||
|
||||
|
||||
<sect2><title><guilabel>CPU Utilization</guilabel> tab</title>
|
||||
<para>When you click the <guilabel>CPU Utilization</guilabel> tab, histograms open for each CPU
|
||||
on the system, as
|
||||
shown in the following screenshot:
|
||||
</para>
|
||||
<para><graphic fileref="cpu.png"/></para>
|
||||
<para>The histograms show information about user (red), system (blue), and nice priority (green) command utilization.</para>
|
||||
</sect2>
|
||||
|
||||
<sect2><title><guilabel>Memory</guilabel> tab</title>
|
||||
<para>The <guilabel>Memory</guilabel> tab is still under development. In a future release of CSPM,
|
||||
the <guilabel>Memory</guilabel> tab will graphically show how much memory processes use, from most to least. </para>
|
||||
</sect2>
|
||||
|
||||
<sect2><title><guilabel>Network</guilabel> tab</title>
|
||||
<para>When you click the <guilabel>Network</guilabel> tab, histograms that show the amount of traffic on the system's loopback device and each network device are displayed, as shown in the following screenshot.
|
||||
</para>
|
||||
<para><graphic fileref="network.png"/></para>
|
||||
<para>Sends are shown in red and receives are shown in blue.</para>
|
||||
</sect2>
|
||||
|
||||
<sect2><title><guilabel>Storage</guilabel> tab</title>
|
||||
<para>When you click the <guilabel>Storage</guilabel> tab, a collection of histograms opens that
|
||||
show data
|
||||
for controllers, disks, and partitions.
|
||||
The key at the bottom of the histograms tells which
|
||||
color of histogram box corresponds to which type of device.
|
||||
</para>
|
||||
<para><graphic fileref="storage.png"/></para>
|
||||
<para>The screenshot
|
||||
displays purple for controllers, green for disks, and orange for partitions.
|
||||
The red lines represent
|
||||
reads from the devices and the blue lines represent writes to the devices.</para>
|
||||
<para>To see information about a partition (such as file system name, space used, and
|
||||
space available), right-click the partition's histogram and then left-click <guimenuitem>Properties</guimenuitem>. A
|
||||
Partition Status window opens that displays information about the selected partition.</para>
|
||||
<para><graphic fileref="snapshot9.png"/></para>
|
||||
</sect2>
|
||||
|
||||
<sect2><title><guilabel>Tests</guilabel> tab</title>
|
||||
<para>The <guilabel>Tests</guilabel> tab opens a list of tests that can be run on the system
|
||||
and is useful, for example, for quality assurance personnel who need to load test systems when testing hardware or software.</para>
|
||||
</sect2>
|
||||
|
||||
<sect2><title><guilabel>Test Summary</guilabel> tab</title>
|
||||
<para>The <guilabel>Test Summary</guilabel> tab contains test output and utilization numbers for test runs.
|
||||
You can print these test results and keep them for your records.</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
</article>
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 8.6 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 10 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 8.5 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 102 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 7.7 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 8.4 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 5.0 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 15 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 15 KiB |
File diff suppressed because it is too large
Load Diff
Binary file not shown.
|
After Width: | Height: | Size: 1.7 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.2 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 6.1 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 5.9 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 3.9 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 5.0 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 4.5 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 969 B |
Binary file not shown.
|
After Width: | Height: | Size: 1.9 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.6 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 3.1 KiB |
|
|
@ -0,0 +1,881 @@
|
|||
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
|
||||
|
||||
<article id="index">
|
||||
<title>Ext2fs Undeletion of Directory Structures mini-HOWTO</title>
|
||||
|
||||
<artheader>
|
||||
|
||||
<author>
|
||||
|
||||
<firstname>Tomas</firstname>
|
||||
<surname>Ericsson</surname>
|
||||
<affiliation>
|
||||
<address>
|
||||
<email>tomase@matematik.su.se</email>
|
||||
</address>
|
||||
</affiliation>
|
||||
|
||||
</author>
|
||||
|
||||
<revhistory>
|
||||
|
||||
<revision>
|
||||
<revnumber>v0.1.1</revnumber>
|
||||
<date>14 November 2000</date>
|
||||
<authorinitials>T.E.</authorinitials>
|
||||
<revremark>Initial release.</revremark>
|
||||
</revision>
|
||||
|
||||
</revhistory>
|
||||
|
||||
<abstract>
|
||||
|
||||
<para>
|
||||
This document is supposed to be as an complementary to the
|
||||
<emphasis>Ext2fs-Undeletion mini-HOWTO</emphasis> written by
|
||||
Aaron Crane. I really recommend you to carefully study that one before
|
||||
reading this.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Here I will describe a straight forward way of recovering whole
|
||||
directory structures, instead of file by file, that have been removed
|
||||
by a misplaced <emphasis>rm -rf</emphasis>.
|
||||
</para>
|
||||
|
||||
</abstract>
|
||||
|
||||
</artheader>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="intro">
|
||||
<title>Introduction</title>
|
||||
|
||||
<sect2>
|
||||
<title>Disclaimer</title>
|
||||
|
||||
<para>
|
||||
The author is not responsible for damages due actions taken based on
|
||||
this document. You will do everything at your own risk.
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>License</title>
|
||||
|
||||
<para>
|
||||
This document may be distributed only subject to the terms and
|
||||
conditions set forth in the LDP license available at
|
||||
<ulink url="http://www.linuxdoc.org/manifesto.html">
|
||||
http://www.linuxdoc.org/manifesto.html
|
||||
</ulink>
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Feedback</title>
|
||||
|
||||
<para>
|
||||
Any kind of feedback is welcome. Corrections of errors in this text are
|
||||
of great interest. If someone find things described here useful I really
|
||||
would appreciate to hear that from you.
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>New versions of this document</title>
|
||||
|
||||
<para>
|
||||
The latest version of this document will be found at
|
||||
<ulink url="http://www.matematik.su.se/~tomase/ext2fs-undeletion/">
|
||||
http://www.matematik.su.se/~tomase/ext2fs-undeletion/</ulink>
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Acknowledgements</title>
|
||||
|
||||
<para>
|
||||
Thanks to the following persons for correctures etc (in alphabetic
|
||||
order).
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>Gabriel Kihlman</para></listitem>
|
||||
<listitem><para>Richard Nyberg</para></listitem>
|
||||
<listitem><para>Mats Oldin</para></listitem>
|
||||
<listitem><para>Tobias Westerblom</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Background</title>
|
||||
|
||||
<para>
|
||||
This text has been written while solving my own undeletion problems that
|
||||
I had some time ago. I was about to move some directories from one disk
|
||||
to another. The problem was that the extra disk went corrupted directly
|
||||
after the move for some reason.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
So I wanted to get the moved directories back from my original disk.
|
||||
There were totally about 40000 files to recover and I did not feel very
|
||||
much like to search and rename each one of them by hand.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
I wanted to get back the whole structure of directories. The same
|
||||
situation would have appeared if I had made an
|
||||
<emphasis>rm -rf</emphasis> to those directories.
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
|
||||
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="precond">
|
||||
<title>Preconditions</title>
|
||||
|
||||
<para>
|
||||
It is really important that you unmount the affected partition immediately
|
||||
before doing anything else with it. If you have copied around some files
|
||||
in this partition after the accident, then the chance for this method to
|
||||
work has lowered a lot.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Also you must have a quite new kernel, because the
|
||||
2.0.x and below zeroes indirect blocks, which will
|
||||
not make this process to work for files with more than 12 blocks of data.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
I will describe one method of recovery and I will not leave out much for
|
||||
error handling. If you suspect that some step described below went wrong,
|
||||
I do not recommend you to go any further.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="prep">
|
||||
<title>Preparation</title>
|
||||
|
||||
<para>
|
||||
Unmount the partition where you got your deleted files at. I will denote
|
||||
that partition with /dev/hdx1.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# umount /dev/hdx1</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Check the size in blocks of /dev/hdx1.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# fdisk -l /dev/hdx</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Now you need to have an extra partition of the same size as
|
||||
/dev/hdx1, to be able to act safely. Suppose that you
|
||||
have an empty harddrive located at /dev/hdy.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# fdisk /dev/hdy</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Create a partition with the same size as /dev/hdx1.
|
||||
Here <emphasis>size</emphasis> is the size in blocks (each block is
|
||||
1024 kB) of /dev/hdx1 taken from above.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
I am using <emphasis>fdisk</emphasis> version 2.10f
|
||||
and if you have another version the <emphasis>fdisk</emphasis>
|
||||
interaction below may not be the same.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
fdisk: n <- Add a new partition.
|
||||
fdisk: p <- Primary partition.
|
||||
fdisk: <- Just press return to chose the default first cylinder.
|
||||
fdisk: +sizeK <- Make a partition of the same size as /dev/hdx1.
|
||||
fdisk: w <- Write table to disk and exit.</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Now copy the content of the original partition to that extra one.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# dd if=/dev/hdx1 of=/dev/hdy1 bs=1k</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This process may take quite a long time dependent of how big the partition
|
||||
is. You can get the job done faster by increasing the blocksize,
|
||||
<emphasis>bs</emphasis>, but then you need to get the division of the
|
||||
partition by <emphasis>bs</emphasis> to have a remainder of zero.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
From now on we will only work with that copy of the source partition to
|
||||
be able to step back if something goes wrong.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="find">
|
||||
<title>Finding inodes for deleted directories</title>
|
||||
|
||||
<para>
|
||||
We will try to find out the inode numbers of the deleted directories.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# debugfs /dev/hdy1</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Walk to that place in the structure where the directories were located
|
||||
before the deletion. You can use <emphasis>ls</emphasis> and
|
||||
<emphasis>cd</emphasis> inside <emphasis>debugfs</emphasis>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
debugfs: ls -l</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Example of output from the above command.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
179289 20600 0 0 0 17-Feb-100 18:26 file-1
|
||||
918209 40700 500 500 4096 16-Jan-100 15:18 file-2
|
||||
160321 41777 0 0 4096 3-Jun-100 06:13 file-3
|
||||
177275 60660 0 6 0 5-May-98 22:32 file-4
|
||||
229380 100600 500 500 89891 19-Dec-99 15:40 file-5
|
||||
213379 120777 0 0 17 16-Jan-100 14:24 file-6</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Description of the fields.
|
||||
</para>
|
||||
|
||||
<orderedlist>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Inode number.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
|
||||
<para>
|
||||
First two (or one) numbers represents the kind of inode we got:
|
||||
</para>
|
||||
|
||||
<para>2 = Character device</para>
|
||||
<para>4 = Directory</para>
|
||||
<para>6 = Block device</para>
|
||||
<para>10 = Regular file</para>
|
||||
<para>12 = Symbolic link</para>
|
||||
|
||||
<para>
|
||||
Last four numbers are the usual Unix rights.
|
||||
</para>
|
||||
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Owner in number representation.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Group in number representation.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Size in bytes.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Date (Here we can see the Y2K bug =)).
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Time.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Filename.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
</orderedlist>
|
||||
|
||||
<para>
|
||||
Now dump the mother directory to disk. Here <emphasis>inode</emphasis> is
|
||||
the corresponding inode number (do not forget the '<' and '>').
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
debugfs: dump <inode> debugfs-dump</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Get out of <emphasis>debugfs</emphasis>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
debugfs: quit</programlisting>
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="analyse">
|
||||
<title>Analyse of directory dump</title>
|
||||
|
||||
<para>
|
||||
View the dumped inode in a readable format.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# xxd debugfs-dump | less</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Every entry consist of five fields. For the first two fields the bytes
|
||||
representing the field comes in backward order. That means the first byte
|
||||
is the least significant.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Description of the fields.
|
||||
</para>
|
||||
|
||||
<orderedlist>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Four bytes - Inode number.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Two bytes - Directory entry length.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
One byte - Filename length (1-255).
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
|
||||
<para>
|
||||
One byte - File type (0-7).
|
||||
</para>
|
||||
|
||||
<para>0 = Unknown</para>
|
||||
<para>1 = Regular file</para>
|
||||
<para>2 = Directory</para>
|
||||
<para>3 = Character device</para>
|
||||
<para>4 = Block device</para>
|
||||
<para>5 = FIFO</para>
|
||||
<para>6 = SOCK</para>
|
||||
<para>7 = Symbolic link</para>
|
||||
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Filename (1-255 characters).
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
</orderedlist>
|
||||
|
||||
<para>
|
||||
If an entry in the directory is to be deleted, then the second field at
|
||||
the entry before will be increased by the value of the deleted entrys
|
||||
second field.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If a filename is renamed to a shorter one, then the third field will be
|
||||
decreased.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The first entry you will see is the directory itself, represented by a
|
||||
dot.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Suppose that we have the following directory entry.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
c1 02 0e 00 40 00 05 01 'u' 't' 'i' 'l' 's'</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Then the inode would be e02c1 in hexadecimal representation or 918209 in
|
||||
decimal. The next entry would be located after 64 bytes (40 in hex). We
|
||||
see that the filename consist of 5 bytes ("utils") and the file type (01)
|
||||
is a regular file.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Now recalculate the directories inode numbers in decimal representation.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you do not like to calculate this by hand I have made a small program
|
||||
in C that will do this for you. The program takes as input a directory
|
||||
dump (created by <emphasis>debugfs</emphasis> as described in
|
||||
<xref linkend="find">). The output (at stdout) consist of each entrys
|
||||
inode number and filename.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Before you run the program you need to load the dump into a hexeditor and
|
||||
change the <emphasis>directory entry length</emphasis> field at the entry
|
||||
before the one you want to get back. But it is simple. If we name the
|
||||
field before to <emphasis>x</emphasis> and the field at the entry you want
|
||||
to get back to <emphasis>y</emphasis>. Then change <emphasis>x</emphasis>
|
||||
to <emphasis>x - y</emphasis>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The program called <emphasis>e2dirana</emphasis> (ext2fs directory
|
||||
analyse) can be found at
|
||||
<ulink url="http://www.matematik.su.se/~tomase/ext2fs-undeletion/">
|
||||
http://www.matematik.su.se/~tomase/ext2fs-undeletion/</ulink>
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="locate">
|
||||
<title>Locating deleted inodes</title>
|
||||
|
||||
<para>
|
||||
Get a list of all deleted inodes.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# echo lsdel | debugfs /dev/hdy1 > lsdel.out</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
One problem here is that <emphasis>debugfs</emphasis> will not give the
|
||||
inode numbers to files that are zero in size (you probably have some in
|
||||
your /etc directory for instance). I will tell how to solve this problem
|
||||
in <xref linkend="recalc"> and <xref linkend="final">.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Load "lsdel.out" into a texteditor. The list of inodes should be sorted in
|
||||
time. Try to remember exactly what time you did that
|
||||
<emphasis>rm -rf</emphasis>. Probably it was the the last items you
|
||||
deleted and then they will be located at the bottom of the list, because it
|
||||
is sorted in time. Delete all lines that has nothing of interest. Save as
|
||||
"lsdel.out-selected".
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Now we will cut away everything except the inodes.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# cut -b 1-8 lsdel.out-selected | tr -d " " > inodes</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To be sure, check that the deleted directories found above have their
|
||||
inodes in the list.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# grep ^inode$ inodes</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Where <emphasis>inode</emphasis> is the corresponding inode number.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="activate">
|
||||
<title>Activating inodes</title>
|
||||
|
||||
<para>
|
||||
Now it is time for changing some flags of the deleted inodes.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Copy the following 6 lines into a file named "make-debugfs-input".
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
#!/bin/sh
|
||||
awk '{ print "mi <" $1 ">\n"\
|
||||
"\n\n\n\n\n\n\n"\
|
||||
"0\n"\
|
||||
"1\n"\
|
||||
"\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n" }'</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This will simulate the user input when editing the inodes manually.
|
||||
We will set <emphasis>deletion time</emphasis> to 0
|
||||
and <emphasis>link count</emphasis> to 1.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
I am using <emphasis>debugfs</emphasis> version 1.18 and if you have
|
||||
another version you should check if you need to adjust the number of
|
||||
returns above.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<para>
|
||||
Now change the inodes.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# ./make-debugfs-input < inodes | debugfs -w /dev/hdy1 | tail -c 40</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If all went well it should end with "Triple Indirect Block [0] debugfs:".
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="add">
|
||||
<title>Adding directory entries</title>
|
||||
|
||||
<para>
|
||||
Start up <emphasis>debugfs</emphasis> in read-write mode.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# debugfs -w /dev/hdy1</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Now you should add the deleted directories to the directory were they were
|
||||
located before deletion.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
debugfs: link <inode> directoryname</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Where <emphasis>inode</emphasis> is the inode number and
|
||||
<emphasis>directoryname</emphasis> is the directoryname.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
After you have added the links you will notice that the directories have
|
||||
popped up in the current directory. You can now list their contents (from
|
||||
<emphasis>debugfs</emphasis>).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
But the size shown for each directory is zero and that need to be fixed,
|
||||
otherwise they will look empty with <emphasis>ls</emphasis> from the
|
||||
shell.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Get out of <emphasis>debugfs</emphasis>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
debugfs: quit</programlisting>
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="recalc">
|
||||
<title>Recalculation</title>
|
||||
|
||||
<para>
|
||||
Now it is time to call <emphasis>e2fsck</emphasis> to recalculate the
|
||||
sizes and checksums.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
I am using <emphasis>e2fsck</emphasis> version 1.18 and if you have
|
||||
another version you should check if some parameters or interaction have
|
||||
changed.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<para>
|
||||
If you know that you do <emphasis>not</emphasis> have any files with the
|
||||
size of zero that you want to recover you can do the following and skip
|
||||
the rest of this section (Of course you can leave out the
|
||||
<emphasis>y</emphasis> parameter, but then you need to answer all
|
||||
questions by hand and it may take a lot of time.).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# e2fsck -f -y /dev/hdy1 > e2fsck.out 2>&1</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you instead want the zero files back you have to answer
|
||||
<emphasis>no</emphasis> to all questions about clearing entries and
|
||||
<emphasis>yes</emphasis> to the other ones.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Copy the following 7 lines into a file named "e2fsck-wrapper".
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
#!/usr/bin/expect -f
|
||||
set timeout -1
|
||||
spawn /sbin/e2fsck -f $argv
|
||||
expect {
|
||||
"Clear<y>? " { send "n" ; exp_continue }
|
||||
"<y>? " { send "y" ; exp_continue }
|
||||
}</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Run the script.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# ./e2fsck-wrapper /dev/hdy1 > e2fsck.out 2>&1</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Examine "e2fsck.out" to see what <emphasis>e2fsck</emphasis> thought about
|
||||
your partition.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="lostnfnd">
|
||||
<title>If /lost+found not empty</title>
|
||||
|
||||
<para>
|
||||
Some of the directory and files may not pop-up at their right places.
|
||||
Instead they will be located in /lost+found with names after their inode
|
||||
numbers.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
In this case the pointer at the ".." directory entry probably have been
|
||||
increased and will point to one of the later entrys in the directory (of
|
||||
some reason I do not know, maybe it is a fs bug).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Examine <emphasis>pass 3</emphasis> (where directory connectivity is
|
||||
checked) of "e2fsck.out". There you will find which directories that are
|
||||
affected. Dump those to disk (as described in <xref linkend="find">).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Run
|
||||
<ulink url="http://www.matematik.su.se/~tomase/ext2fs-undeletion/">
|
||||
<emphasis>e2dirana</emphasis></ulink>
|
||||
both with and without the <emphasis>p</emphasis> parameter (it changes the
|
||||
pointer at the ".." directory entry). Here <emphasis>dump</emphasis> is
|
||||
the dumped directory.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# e2dirana dump > dump1
|
||||
# e2dirana -p dump > dump2</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Compare the outputs.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# diff dump1 dump2</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If they are not the same there are missing files in that directory. Then
|
||||
move those files from /lost+found to their right place. Here
|
||||
<emphasis>dest</emphasis> is a symbolic link to the destination directory.
|
||||
Put the output in a script and run it if you agree.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# diff dump1 dump2 |\
|
||||
tail -n $[`diff dump1 dump2 | wc -l`-1] | cut -b 3- |\
|
||||
sed -e 's/^\([^ ]*\) \(.*\)$/mv lost+found\/#\1 dest\/"\2"/' |\
|
||||
sed -e 's/!/"\\\!"/g'</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Repeat all this until /lost+found is empty.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="final">
|
||||
<title>Final touch</title>
|
||||
|
||||
<para>
|
||||
If in <xref linkend="recalc"> you choosed to get files with the size of
|
||||
zero back you now have a problem, because those files has a non-zero
|
||||
deletion time and their link count is zero. That means that every time
|
||||
<emphasis>e2fsck</emphasis> is running it will prompt to remove (clear)
|
||||
those files.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The easy way to solve this is to copy the whole directory structure to
|
||||
another place (it can be the same partition) and then delete the old
|
||||
directory structure. Otherwise you will have to locate those inodes and
|
||||
change them with <emphasis>debugfs</emphasis>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Now if everything have went well, things should have been restored to its
|
||||
original state before deletion. At least it did for me and in those tests
|
||||
I have made while writing this. Be sure that you have brought up to the
|
||||
preconditions described in <xref linkend="precond">.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="ref">
|
||||
<title>References</title>
|
||||
|
||||
<para>
|
||||
<emphasis>Linux Ext2fs Undeletion mini-HOWTO</emphasis>, v1.3
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>Aaron Crane</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>
|
||||
<emphasis>Design and Implementation of the Second Extended Filesystem</emphasis>,
|
||||
<ulink url="http://e2fsprogs.sourceforge.net/ext2intro.html">
|
||||
http://e2fsprogs.sourceforge.net/ext2intro.html</ulink>
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>Rémy Card, Laboratoire MASI--Institut Blaise Pascal</para></listitem>
|
||||
<listitem><para>Theodore Ts'o, Massachussets Institute of Technology</para></listitem>
|
||||
<listitem><para>Stephen Tweedie, University of Edinburgh</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>
|
||||
<emphasis>Kernel Source for Linux 2.2.16</emphasis>
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>linux/include/linux/ext2_fs.h</para></listitem>
|
||||
<listitem><para>linux/fs/ext2/namei.c</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
</sect1>
|
||||
|
||||
</article>
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,12 @@
|
|||
<!doctype article public "-//OASIS//DTD DocBook V3.1//EN">
|
||||
<ARTICLE ID="INDEX"><ARTHEADER><TITLE>HOWTO-HOWTO</TITLE>
|
||||
<PUBDATE>v1.4 12 Jun, 2000</PUBDATE>
|
||||
<AUTHOR><FIRSTNAME>Mark</FIRSTNAME>
|
||||
<OTHERNAME>F.</OTHERNAME>
|
||||
<SURNAME>Komarinski</SURNAME></AUTHOR>
|
||||
<ABSTRACT><PARA>List the tools, procedures, and hints to get HOWTO
|
||||
authors up to speed and writing. Replaced by the
|
||||
<ulink url="http://linuxdoc.org/LDP/LDP-Author-Guide/">LDP Author Guide</ulink>
|
||||
</PARA></ABSTRACT>
|
||||
</ARTHEADER>
|
||||
</ARTICLE>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 27 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 40 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 44 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 107 KiB |
|
|
@ -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 & 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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -0,0 +1,674 @@
|
|||
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
|
||||
|
||||
<article id="index">
|
||||
|
||||
<!-- Header -->
|
||||
|
||||
<artheader>
|
||||
|
||||
<!-- title of HOWTO, include the word HOWTO -->
|
||||
|
||||
<title>KDE Kiosk Mode HOWTO</title>
|
||||
|
||||
<author>
|
||||
<firstname>Roland</firstname>
|
||||
<surname>Fehrenbacher</surname>
|
||||
<affiliation>
|
||||
<address>
|
||||
<email>rfehrenb@transtec.de</email>
|
||||
</address>
|
||||
</affiliation>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Peter</firstname>
|
||||
<surname>Kruse</surname>
|
||||
<affiliation>
|
||||
<address>
|
||||
<email>Peter.Kruse@wolnet.de</email>
|
||||
</address>
|
||||
</affiliation>
|
||||
</author>
|
||||
|
||||
<revhistory>
|
||||
<revision>
|
||||
<revnumber>1.4</revnumber>
|
||||
<date>2002-09-26</date>
|
||||
<authorinitials>gjf</authorinitials>
|
||||
<revremark>Archived.</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>$Revision: 1.1 $</revnumber>
|
||||
<date>$Date: 2002/09/26 15:20:35 $</date>
|
||||
<authorinitials>$Author: gferg $</authorinitials>
|
||||
<revremark>
|
||||
|
||||
<comment>
|
||||
$Log: KDE-Kiosk-Mode.sgml,v $
|
||||
Revision 1.1 2002/09/26 15:20:35 gferg
|
||||
archived
|
||||
|
||||
Revision 1.3 2001/08/14 07:44:07 kruse
|
||||
nicer formatting.
|
||||
|
||||
Revision 1.2 2001/08/14 07:42:50 pkruse
|
||||
.
|
||||
|
||||
Revision 1.1 2001/08/03 13:56:20 pkruse
|
||||
almost published.
|
||||
|
||||
Revision 1.4 2001/07/31 14:15:21 pkruse
|
||||
prepare to check in linuxdoc cvs.
|
||||
|
||||
Revision 1.3 2001/07/31 13:39:12 pkruse
|
||||
variable and filename docbook tags added.
|
||||
|
||||
Revision 1.2 2001/07/31 11:05:51 pkruse
|
||||
first revision.
|
||||
|
||||
Revision 1.1 2001/07/31 10:49:51 pkruse
|
||||
Initial revision
|
||||
</comment>
|
||||
|
||||
</revremark>
|
||||
</revision>
|
||||
|
||||
<!-- Additional (*earlier*) revision histories go here -->
|
||||
</revhistory>
|
||||
|
||||
<abstract>
|
||||
|
||||
<para>
|
||||
The requirements for the desktop environment of users in a large
|
||||
network environment is often very different to a typical homeuser. The
|
||||
number of applications that these users need to run is usually very
|
||||
limited, and the users themselves are not very experienced in solving
|
||||
computing related problems. The administrators of the network
|
||||
therefore need to ensure that the required applications run reliably,
|
||||
and can be started by the users with a minimum of hassle. For
|
||||
security, stability, and also administrative reasons it is then
|
||||
advisable to provide only the absolutely necessary applications and
|
||||
functionality.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
With the advent of modern desktop technology like KDE, this goal has become
|
||||
harder to achieve. Interoperability between different desktop programs, ease
|
||||
of configuration by configuration engines, etc. allow the user a great deal
|
||||
of control over her/his desktop, which is great when needed. The above large
|
||||
network scenario, however, is not addressable in standard KDE. This is where
|
||||
the restricted mode tries to fill in the gap.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<important>
|
||||
<para>
|
||||
<emphasis role="strong">Archived Document Notice: </emphasis>
|
||||
This document has been archived by the LDP because it does not apply
|
||||
to modern Linux systems. It is no longer being actively maintained.
|
||||
Further information on this topic can be found at
|
||||
<ulink url="http://www.brigadoon.de/peter/kde/">http://www.brigadoon.de/peter/kde/</ulink>.
|
||||
</para>
|
||||
</important>
|
||||
</para>
|
||||
</abstract>
|
||||
|
||||
</artheader>
|
||||
|
||||
|
||||
<!-- Section1: intro -->
|
||||
|
||||
<sect1 id="intro">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>
|
||||
This document describes a by-product of a project, in which a large
|
||||
number of Linux based workstations were provided. Although a
|
||||
kiosk-mode patch exists for KDE 1, this document assumes KDE 2 and the
|
||||
patches apply to KDE version 2.1.1(2).
|
||||
</para>
|
||||
|
||||
<!-- Section2: copyright -->
|
||||
|
||||
<sect2 id="copyright">
|
||||
<title>Copyright Information</title>
|
||||
|
||||
<para>
|
||||
This document is copyrighted (c) 2001 Peter Kruse and Roland
|
||||
Fehrenbacher and is distributed under the terms of the Linux
|
||||
Documentation Project (LDP) license, stated below.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Unless otherwise stated, Linux HOWTO documents are
|
||||
copyrighted by their respective authors. Linux HOWTO documents may
|
||||
be reproduced and distributed in whole or in part, in any medium
|
||||
physical or electronic, as long as this copyright notice is
|
||||
retained on all copies. Commercial redistribution is allowed and
|
||||
encouraged; however, the authors would like to be notified of any
|
||||
such distributions.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
All translations, derivative works, or aggregate works
|
||||
incorporating any Linux HOWTO documents must be covered under this
|
||||
copyright notice. That is, you may not produce a derivative work
|
||||
from a HOWTO and impose additional restrictions on its
|
||||
distribution. Exceptions to these rules may be granted under
|
||||
certain conditions; please contact the Linux HOWTO coordinator at
|
||||
the address given below.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
In short, we wish to promote dissemination of this
|
||||
information through as many channels as possible. However, we do
|
||||
wish to retain copyright on the HOWTO documents, and would like to
|
||||
be notified of any plans to redistribute the HOWTOs.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you have any questions, please contact
|
||||
<email>linux-howto@metalab.unc.edu</email>
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<!-- Section2: disclaimer -->
|
||||
|
||||
<sect2 id="disclaimer">
|
||||
<title>Disclaimer</title>
|
||||
|
||||
<para>
|
||||
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,
|
||||
the authors do not take any responsibility for that.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
All copyrights are held by their 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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Naming of particular products or brands should not be seen
|
||||
as endorsements.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You are strongly recommended to take a backup of your system
|
||||
before major installation and backups at regular intervals.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<!-- Section2: newversions-->
|
||||
|
||||
<sect2 id="newversions">
|
||||
<title>New Versions</title>
|
||||
|
||||
<para>
|
||||
This document and the patches are available at
|
||||
<ulink url="http://www.brigadoon.de/peter/kde">http://www.brigadoon.de/peter/kde</ulink>.
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<!-- Section2: credits -->
|
||||
|
||||
<sect2 id="credits">
|
||||
<title>Credits</title>
|
||||
|
||||
<para>
|
||||
<email>Werner.Westerkamp (at) lbbw.de</email> for giving useful
|
||||
tips, and proof-reading this HOWTO
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<email>remalone (at) sympatico.ca</email> for first-time testing
|
||||
the instructions given here
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<!-- Section2: feedback -->
|
||||
|
||||
<sect2 id="feedback">
|
||||
<title>Feedback</title>
|
||||
|
||||
<para>
|
||||
Please send any comments, corrections or additions to one of the authors.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
|
||||
<!-- Section1: intro: END -->
|
||||
|
||||
|
||||
<sect1 id="motivation">
|
||||
<title>Motivation</title>
|
||||
|
||||
<para>
|
||||
The following requirements had to be met:
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
|
||||
<listitem>
|
||||
<para>The user should not be able to open an interactive shell
|
||||
(Terminal), or run arbitrary commands,
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
The user should not have a view to the filesystem, so no
|
||||
filemanager,
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>The user should not be able to modify or create files
|
||||
directly by means provided by KDE (no editor, menuedit, etc.).
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Note that these are not requirements for the applications that run under KDE.
|
||||
Every application should make sure by itself, that these requirements are met.
|
||||
It is known, that of course many applications have an Open File Dialog, and
|
||||
thus could modify Files under .kde and so make it possible to run arbitrary
|
||||
commands.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The restrictions should only apply when an environment variable
|
||||
<EnVar>KDE_MODE</EnVar> is
|
||||
set to ``restricted''. If it is not set, a normal KDE Desktop should open.
|
||||
|
||||
It follows, that the user can only run applications that are found in
|
||||
the Application menu. So the administrator must be able to provide the
|
||||
applications. A tool is needed to add, remove and modify entries in
|
||||
the menu.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<!-- Section1: samples: END -->
|
||||
|
||||
|
||||
<!-- Section1: structure -->
|
||||
|
||||
<sect1 id="implementation">
|
||||
<title>Implementation</title>
|
||||
|
||||
<sect2 id="patches">
|
||||
<title>Source Code Patches</title>
|
||||
|
||||
<para>
|
||||
Some files in kdebase-2.1.1 have to be patched:
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
appletop_mnu.cpp.patch: Applets on the panel can be moved and removed, but
|
||||
the Preferences dialog is disabled.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
k_mnu.cpp.patch: <guimenuitem>Run Command...</guimenuitem> and
|
||||
<guisubmenu>Configure Panel</guisubmenu> entries are
|
||||
removed from the standard <guimenu>K</guimenu> Menu
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
khc_man.cc.patch: Online Help is completely disabled. This would
|
||||
open konqueror.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
konq_popupmenu.cc.patch: right-mouse menu on icons on the desktop
|
||||
are reduced to <guimenuitem>Cut</guimenuitem>,
|
||||
<guimenuitem>Copy</guimenuitem>, <guimenuitem>Paste</guimenuitem>,
|
||||
<guimenuitem>Delete</guimenuitem>, ... but no <guimenuitem>Open With
|
||||
...</guimenuitem>,
|
||||
no <guimenuitem>Edit File Type...</guimenuitem> and no
|
||||
<guimenuitem>Poperties...</guimenuitem> dialogs.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
pagerapplet.cpp.patch: on minipager selection of type
|
||||
(<guimenuitem>Preview</guimenuitem>,
|
||||
<guimenuitem>Number</guimenuitem>,
|
||||
<guimenuitem>Name</guimenuitem>) is disabled. this caused trouble in
|
||||
multihead environment.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
panel.cpp.patch: right mouse menu on Panel is disabled.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
</itemizedlist>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="global-modification">
|
||||
<title>Global modifications</title>
|
||||
|
||||
<para>
|
||||
|
||||
Instead of a dcop call, a program <command>screensaver</command> is
|
||||
executed, which must be found in the <envar>PATH</envar>. Just create
|
||||
a script called <command>screensaver</command>
|
||||
with the following contents:
|
||||
|
||||
<programlisting>
|
||||
#!/bin/bash
|
||||
|
||||
dcop kdesktop KScreensaverIface lock
|
||||
</programlisting>
|
||||
|
||||
make it executable and put it in <filename>$KDEDIR/bin</filename>.
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
Instead of the normal procedure, a program <command>klogout</command>
|
||||
is called, which must be found in the <envar>PATH</envar>. Create a
|
||||
script called <command>klogout</command> with the following contents:
|
||||
|
||||
<programlisting>
|
||||
#!/bin/bash
|
||||
|
||||
dcop kdesktop KDesktopIface logout
|
||||
</programlisting>
|
||||
make it executable and put it in <filename>$KDEDIR/bin</filename>,
|
||||
where <filename>$KDEDIR</filename> is the install directory of KDE and
|
||||
<filename>$KDEDIR/bin</filename> is found in your
|
||||
<EnVar>PATH</EnVar>.
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
krootwm.cc.patch: klogout is executed instead of a dcop call
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
systemtrayapplet.cpp.patch: again call of klogout and screensaver
|
||||
instead of dcop calls.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
workspace.cpp.patch: call of klogout instead of dcop call.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
</itemizedlist>
|
||||
|
||||
<para>
|
||||
Everything else can be done with normal configuration, that is:
|
||||
|
||||
(Configuration files can be found in <filename>$KDEDIR/share/config</filename>)
|
||||
|
||||
Remove Trash, Templates and Autostart Icons from the desktop and disable
|
||||
<keycombo action="Simul"><keycap>Alt</keycap><keycap>F2</keycap></keycombo>
|
||||
by modifying <filename>kdeglobals</filename>. Make sure the following
|
||||
entries exist:
|
||||
|
||||
<programlisting>
|
||||
[Paths]
|
||||
|
||||
Trash=$HOME/.kde2/Trash/
|
||||
|
||||
Autostart=$HOME/.kde2/Autostart/
|
||||
|
||||
Templates=$HOME/.kde2/Templates/
|
||||
|
||||
Desktop=$HOME/.kde2/Desktop/
|
||||
|
||||
|
||||
[Global Keys]
|
||||
|
||||
Execute command=
|
||||
</programlisting>
|
||||
|
||||
(it may be <filename>.kde</filename> instead of <filename>.kde2</filename>)
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
disable Desktop menu and tips on start. Make sure the following entry
|
||||
exists in <filename>kdesktoprc</filename>:
|
||||
|
||||
<programlisting>
|
||||
[Mouse Buttons]
|
||||
|
||||
Right=
|
||||
|
||||
[General]
|
||||
|
||||
TipsOnStart=false
|
||||
</programlisting>
|
||||
|
||||
You could also login as the special user, and configure it only for
|
||||
him, then the config files are found in <filename>$KDEHOME/share/config</filename> where
|
||||
<filename>$KDEHOME</filename> is normally <filename>$HOME/.kde</filename>.
|
||||
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2 id="kde-mode">
|
||||
<title>How to set the variable KDE_MODE</title>
|
||||
|
||||
<para>
|
||||
To answer this, you must understand what happens after you
|
||||
successfully authorized yourself to the system: Depending on your
|
||||
distribution, some scripts are executed, from which one should be
|
||||
modified to set <EnVar>KDE_MODE</EnVar>. There is a script called
|
||||
<Command>Xsession</Command> under <filename>/etc/X11/xdm</filename> or
|
||||
<filename>/usr/X11R6/lib/xdm</filename>, which you could modify, or
|
||||
<Command>startkde</Command>, that is located under
|
||||
<filename>$KDEDIR/bin</filename>. Note however, that the variable
|
||||
must be set prior to calling the kde processes.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Since we had the need to make a setup for a big environment (now
|
||||
reaching 300 users) we wrote an application that enables us to
|
||||
administer. It also creates the KDE Menus. It writes a file called
|
||||
<filename>.env.sh</filename> in a user's home directory, that will be
|
||||
sourced in <Command>Xsession</Command>. That is what you could do. So
|
||||
you could put in <filename>.env.sh</filename> of that specific user's
|
||||
home directory:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
#!/bin/sh
|
||||
|
||||
KDE_MODE="restricted"
|
||||
|
||||
export KDE_MODE
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
and add to Xsession, somewhere prior to calling startkde:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
if [ -f $HOME/.env.sh ]; then
|
||||
|
||||
. $HOME/.env.sh
|
||||
|
||||
fi
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
We also have two kdedirs that looks like to separate installations of
|
||||
KDE, this was neccessary so "normal" users could still have a
|
||||
full-featured KDE. So we have an original kdedir, and a restricted
|
||||
kdedir, in which we removed entries under
|
||||
<filename>share/applnk</filename> and set the variable
|
||||
<envar>KDEDIR</envar> (under KDE 2 the variable <envar>KDEDIRS</envar>
|
||||
was introduced but <envar>KDEDIR</envar> is still used). The files
|
||||
under <filename>share/applnk</filename> make up the menu. Caution, you
|
||||
cannot just remove all files there, because some are needed to
|
||||
initialize KDE.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You also set the Variable <envar>KDEDIR</envar> in
|
||||
<command>Xsession</command>, after sourcing
|
||||
<filename>.env.sh</filename> like this:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
case "$KDE_MODE" in
|
||||
|
||||
restricted)
|
||||
|
||||
KDEDIR=/usr/local/kde/restricted_kdedir
|
||||
|
||||
;;
|
||||
|
||||
*)
|
||||
|
||||
KDEDIR=/usr/local/kde
|
||||
|
||||
esac
|
||||
|
||||
export KDEDIR
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
Replace <filename>/usr/local/kde</filename> with the install directory
|
||||
of your KDE. The contents of
|
||||
<filename>/usr/local/kde/restricted_kdedir</filename> looks like:
|
||||
|
||||
<screen>
|
||||
|
||||
bin -> ../bin
|
||||
|
||||
cgi-bin -> ../cgi-bin
|
||||
|
||||
etc -> ../etc
|
||||
|
||||
lib -> ../lib
|
||||
|
||||
share
|
||||
|
||||
</screen>
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
only share is a real directory, every other directory is a symbolic
|
||||
link pointing to original
|
||||
kdedir. <filename>/usr/local/kde/restricted_kdedir/share</filename>
|
||||
has the following contents:
|
||||
|
||||
<screen>
|
||||
|
||||
aclocal -> ../../share/aclocal
|
||||
|
||||
applnk
|
||||
|
||||
apps -> ../../share/apps
|
||||
|
||||
autostart -> ../../share/autostart
|
||||
|
||||
config -> ../../share/config
|
||||
|
||||
doc -> ../../share/doc
|
||||
|
||||
fonts -> ../../share/fonts
|
||||
|
||||
icons -> ../../share/icons
|
||||
|
||||
locale -> ../../share/locale
|
||||
|
||||
mimelnk -> ../../share/mimelnk
|
||||
|
||||
services -> ../../share/services
|
||||
|
||||
servicetypes -> ../../share/servicetypes
|
||||
|
||||
sounds -> ../../share/sounds
|
||||
|
||||
templates -> ../../share/templates
|
||||
|
||||
wallpapers -> ../../share/wallpapers
|
||||
|
||||
</screen>
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
only applnk is a real directory. As a minimal requirement remove
|
||||
everything except:
|
||||
|
||||
<screen>
|
||||
|
||||
Settings/Peripherals/mouse.desktop
|
||||
|
||||
Settings/LookNFeel/background.desktop
|
||||
|
||||
/colors.desktop
|
||||
|
||||
/kwinoptions.desktop
|
||||
|
||||
/style.desktop
|
||||
|
||||
/virtualdesktops.desktop
|
||||
|
||||
</screen>
|
||||
|
||||
under <filename>/usr/local/kde/restricted_kdedir/share/applnk</filename>
|
||||
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
|
||||
</article>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
mode: sgml
|
||||
sgml-omittag:t
|
||||
sgml-shorttag:t
|
||||
sgml-namecase-general:t
|
||||
sgml-general-insert-case:lower
|
||||
sgml-minimize-attributes:nil
|
||||
sgml-always-quote-attributes:t
|
||||
sgml-indent-step:1
|
||||
sgml-indent-data:nil
|
||||
sgml-parent-document:nil
|
||||
sgml-exposed-tags:nil
|
||||
sgml-local-catalogs:nil
|
||||
sgml-local-ecat-files:nil
|
||||
End:
|
||||
-->
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,110 @@
|
|||
<!doctype article public "-//OASIS//DTD DocBook V4.1//EN"
|
||||
[
|
||||
<!entity header system "header.sgml">
|
||||
<!entity sectionpamnss SYSTEM "section-pamnss.sgml">
|
||||
<!entity sectionsasl SYSTEM "section-sasl.sgml">
|
||||
<!entity sectionradius SYSTEM "section-radius.sgml">
|
||||
<!entity sectionsamba SYSTEM "section-samba.sgml">
|
||||
<!entity sectiondns SYSTEM "section-dns.sgml">
|
||||
<!entity sectionsendmail SYSTEM "section-sendmail.sgml">
|
||||
<!entity sectionaddress SYSTEM "section-address.sgml">
|
||||
<!entity sectionroaming SYSTEM "section-roaming.sgml">
|
||||
<!entity sectioncertificates SYSTEM "section-certificates.sgml">
|
||||
<!entity sectionssl SYSTEM "section-ssl.sgml">
|
||||
<!entity sectionsecurity SYSTEM "section-security.sgml">
|
||||
<!entity sectionperformance SYSTEM "section-performance.sgml">
|
||||
<!entity sectionttt SYSTEM "section-ttt.sgml">
|
||||
<!entity sectionschemas SYSTEM "section-schemas.sgml">
|
||||
<!entity sectionfiles SYSTEM "section-files.sgml">
|
||||
<!entity fileslapdconf SYSTEM "lih-slapd.conf">
|
||||
<!entity fileldapconf SYSTEM "lih-ldap.conf">
|
||||
<!entity fileschema SYSTEM "lih-schema.conf">
|
||||
<!entity fileldifstructure SYSTEM "lih-structure.ldif">
|
||||
]>
|
||||
<ARTICLE ID="INDEX"><ARTICLEINFO><TITLE>LDAP Implementation HOWTO</TITLE>
|
||||
<PUBDATE>v0.5, 2001-03-30</PUBDATE>
|
||||
<AUTHOR><FIRSTNAME>Roel</FIRSTNAME>
|
||||
<OTHERNAME>van</OTHERNAME>
|
||||
<SURNAME>Meer</SURNAME>
|
||||
<AFFILIATION><ORGNAME><ULINK URL="http://www.linvision.com">Linvision BV</ULINK></ORGNAME>
|
||||
<ADDRESS FORMAT="LINESPECIFIC"><EMAIL>r.vanmeer@linvision.com</EMAIL></ADDRESS></AFFILIATION></AUTHOR>
|
||||
<AUTHOR><FIRSTNAME>Giuseppe</FIRSTNAME>
|
||||
<OTHERNAME>Lo</OTHERNAME>
|
||||
<SURNAME>Biondo</SURNAME>
|
||||
<AFFILIATION><ORGNAME><ULINK
|
||||
URL="http://www.mi.infn.it">INFN MI</ULINK></ORGNAME>
|
||||
<ADDRESS FORMAT="LINESPECIFIC"><EMAIL>giuseppe.lobiondo@mi.infn.it</EMAIL></ADDRESS></AFFILIATION></AUTHOR>
|
||||
<ABSTRACT><PARA>This document describes the technical aspects of storing application data in an ldap server. It focuses on the configuration of various applications to make them ldap-aware. Some applications that assist in handling ldap data are also discussed.</PARA></ABSTRACT>
|
||||
|
||||
<REVHISTORY>
|
||||
<REVISION>
|
||||
<REVNUMBER>0.5</REVNUMBER>
|
||||
<DATE>2001-03-30</DATE>
|
||||
<AUTHORINITIALS>rvm</AUTHORINITIALS>
|
||||
<REVREMARK>Cleanup, fixes, overview rewritten.</REVREMARK></REVISION>
|
||||
<REVISION>
|
||||
<REVNUMBER>0.4</REVNUMBER>
|
||||
<DATE>2001-02-01</DATE>
|
||||
<AUTHORINITIALS>rvm</AUTHORINITIALS>
|
||||
<REVREMARK>Added dns section.</REVREMARK></REVISION>
|
||||
<REVISION>
|
||||
<REVNUMBER>0.3</REVNUMBER>
|
||||
<DATE>2001-01-18</DATE>
|
||||
<AUTHORINITIALS>rvm</AUTHORINITIALS>
|
||||
<REVREMARK>Added MTA sections.</REVREMARK></REVISION>
|
||||
<REVISION>
|
||||
<REVNUMBER>0.2</REVNUMBER>
|
||||
<DATE>2000-11-12</DATE>
|
||||
<AUTHORINITIALS>glb</AUTHORINITIALS>
|
||||
<REVREMARK>Improved section on nss. Added sections about certificates and wrappers.</REVREMARK></REVISION>
|
||||
</REVHISTORY>
|
||||
</ARTICLEINFO>
|
||||
|
||||
<SECT1 ID="OVERVIEW"><TITLE>Overview</TITLE>
|
||||
<SECT2><TITLE>Why this howto?</TITLE>
|
||||
<PARA>I started learning about ldap when my company felt the need for a centralized storage of user account information, and wanted to use ldap for this. I soon found that there were bits and pieces of documantation everywhere, but that there was no document that put it all together. This has been the reason to start it.</PARA>
|
||||
<PARA>Furthermore, Ldap is becoming more widely used every day. I think it is useful that when people are considering to use Ldap, they can get a full overview of which applications are Ldap aware. This might help them to choose their system setup carefully, without throwing everything about every time they want to change something or add functionality.</PARA>
|
||||
|
||||
<PARA>It started out as a project roadmap on how we wanted to implement Ldap for our own uses. But thanks to my employer, <ULINK URL="http://www.linvision.com">Linvision</ULINK>, who gave me the opportunity to do some research on things that weren't really useful to our own cause, it changed from a roadmap to a technical overview of applications that are ldap aware.</PARA>
|
||||
</SECT2>
|
||||
<SECT2><TITLE>What is it about?</TITLE>
|
||||
<PARA>Most of the common services can be authenticated through PAM, Pluggable Authentication Modules. With the pam_ldap and nss_ldap modules, all pamified programs can get their information from LDAP. More information about PAM in general can be found on <ULINK URL="http://www.kernel.org/pub/linux/libs/pam/">the Linux-PAM site</ULINK>. Information about pam_ldap and nss_ldap can be found on the <ULINK URL="http://www.padl.com">padl software</ULINK> site.</PARA>
|
||||
<PARA>For Samba, things are a little difficult at this moment. The current stable Samba versions do not have Ldap support. Ldap support can be found in the HEAD and TNG branch, and probably also in the combined tree. The problem is that samba has it's own usernames and passwords. It does have usage for PAM, in fact, but that is not sufficient to do all the authentication and retrieval of user information. Because the implementation of LDAP in samba is not fully finished yet, there are a few limitations to the use of ldap with samba. From my experiences, the HEAD is at this time (early June 2000) not stable enough, and the performance is unsatisfying. However, when the ldap support is fully functional in the new releases, samba too can be configured to get all of it's user information from ldap.</PARA>
|
||||
<PARA>Another thing that can be stored into an ldap database is DNS. When the amount of machines connected to your network increases, it is no longer feasable to edit the DNS files by hand. When machine accounts are stored into ldap, two simple DNS entries (one for the lookup, and one for the reverse lookup) can easily be added at the same time. This too provides a simplification of system management. Although the storage of DNS entries in an ldap database may not be neccesary for most systems, it may prove useful to some people.</PARA>
|
||||
<PARA>Since sendmail version 8.9 (see <ULINK URL="http://www.sendmail.net/">sendmail.net</ULINK>
|
||||
for more details), sendmail has Ldap support. Postfix and QMail are ldap-aware too. When setting up an email system which has multiple mailhosts and or fallback hosts, it is convenient to store all the information in one place. Normally, every system needs to be configured separately, with the same information. When using ldap, this can be avoided.</PARA>
|
||||
<PARA>Roaming access can also be used with LDAP. Netscape versions 4.5 and up have the possibility to store user data like bookmarks and such via an HTML or LDAP server. This gives users their good old preferences, wherever they log in and use Netscape.</PARA>
|
||||
<PARA>Microsoft's office programs can import address books. Thay can also use an Active Directory service to automagically match emailaddresses to user names or nicknames. With Ldap this can be done on a Linux system, without the need for Microsoft Exchange Server or something the like.</PARA></SECT2>
|
||||
|
||||
<SECT2><TITLE>What is it NOT about?</TITLE>
|
||||
<PARA>First thing: I will try not to talk too much about the actual setup and administration of Ldap itself.
|
||||
There is an excellent Ldap HOWTO available at the Linux Documentation Project that discusses this.</PARA>
|
||||
<PARA>Secondly, I will not discuss things regarding the applications itself, when they have nothing to do with Ldap.</PARA>
|
||||
<PARA>Lastly, in most cases, I cannot tell you if it is wise to use Ldap. I don't have that kind of experience. I can tell you how to do it, if you want, but i cannot tell you if you should. There is plenty documentaion available that discusses the useability of Ldap in general.</PARA>
|
||||
</SECT2>
|
||||
|
||||
<SECT2><TITLE>Acknowledgements</TITLE>
|
||||
<PARA>At first, I would like to thank my employer, <ULINK URL="http://www.linvision.com">Linvision</ULINK>, for giving me the opportunity to work on this document in their time.</PARA>
|
||||
<PARA>Furthermore, I would like to thank the following people, who have contributed to this document in some way (in no particular order): Giuseppe Lo Biondo.</PARA></SECT2>
|
||||
|
||||
<SECT2><TITLE>Disclaimer</TITLE>
|
||||
<PARA>This document is provided as is and should be considered as a work in progress. Several sections are as yet unfinished, and probably a lot of things that should be in here, aren't. I would greatly appreciate any comments on this document, of whatever nature they may be.</PARA>
|
||||
<PARA>In any case, think before you go messing around with your system and don't come to me if it breaks.</PARA></SECT2>
|
||||
|
||||
<SECT2><TITLE>Copyright and license</TITLE>
|
||||
<PARA>Copyright (c) by Roel van Meer, Giuseppe Lo Biondo. This document
|
||||
may be distributed only subject to the terms and conditions set forth in
|
||||
the LDP License at the <ULINK URL="http://www.linuxdoc.org/COPYRIGHT.html">Linux Documentation Project</ULINK>.</PARA></SECT2></SECT1>
|
||||
§ionpamnss;
|
||||
§ionradius;
|
||||
§ionsamba;
|
||||
§iondns;
|
||||
§ionsendmail;
|
||||
§ionaddress;
|
||||
§ionroaming;
|
||||
§ioncertificates;
|
||||
§ionssl;
|
||||
§ionschemas;
|
||||
§ionfiles;
|
||||
</ARTICLE>
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,632 @@
|
|||
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
<!-- for extra DocBook help check http://www-106.ibm.com/developerworks/linux/library/l-docbk.html -->
|
||||
|
||||
<article>
|
||||
<articleinfo>
|
||||
<title>Linux + XFS HOWTO</title><subtitle>Linux on Steroids</subtitle>
|
||||
<author>
|
||||
<firstname>Russel</firstname>
|
||||
<surname>Ingram</surname>
|
||||
<affiliation>
|
||||
<address>
|
||||
<email>ringram@gargoylecc.com</email>
|
||||
</address>
|
||||
</affiliation>
|
||||
</author>
|
||||
|
||||
<date>v1.1, May 12, 2002</date>
|
||||
|
||||
<revhistory>
|
||||
<revision>
|
||||
<revnumber>v1.1</revnumber>
|
||||
<date>2002-05-12</date>
|
||||
<authorinitials>ri</authorinitials>
|
||||
<revremark>
|
||||
Updated sgi cvs info to match current state; made various changes/clarifications based on reader feedback
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v1.02</revnumber>
|
||||
<date>2001-10-08</date>
|
||||
<authorinitials>ri</authorinitials>
|
||||
<revremark>
|
||||
Added some note, blockquote and ulink tags.
|
||||
Corrected error in command section of "Finishing Up".
|
||||
Changed note about e2fsprogs-devel to refer to libuuid.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v1.01</revnumber>
|
||||
<date>2001-10-04</date>
|
||||
<authorinitials>ri</authorinitials>
|
||||
<revremark>
|
||||
Corrected error in "Finishing up" section; various formatting changes
|
||||
</revremark>
|
||||
</revision>
|
||||
</revhistory>
|
||||
|
||||
<abstract><para>
|
||||
This document describes how to build a Linux system that runs
|
||||
on top of the SGI XFS journaling filesystem.
|
||||
</para></abstract>
|
||||
|
||||
</articleinfo>
|
||||
<sect1>
|
||||
<title>Introduction</title>
|
||||
<sect2>
|
||||
<title> Introduction to XFS for Linux </title>
|
||||
<para>
|
||||
This document describes how to build a Linux system that runs
|
||||
on top of the SGI XFS journaling filesystem. From the XFS FAQ: "XFS
|
||||
is a journalling filesystem developed by SGI and used in SGI's IRIX
|
||||
operating system. It is now also available under GPL for linux. It
|
||||
is extremely scalable, using btrees extensively to support large
|
||||
sparse files, and extremely large directories. The journalling capability
|
||||
means no more waiting for fsck's or worrying about meta-data corruption."
|
||||
Essentialy XFS is the filesystem SGI designed for its highend server
|
||||
systems, hence the subtitle of this document, "Linux on Steroids".
|
||||
:-)
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2>
|
||||
<title> Foreword, Feedback, & Credits </title>
|
||||
<para>
|
||||
As a fairly new member of the Irix System Administrator community
|
||||
I have fallen in love with the robustness of the filesystem that
|
||||
has been developed to support Irix (XFS of course). So, needless
|
||||
to say I've been following the porting effort to Linux for quite
|
||||
some time and have dreamed of being able to run my Linux systems
|
||||
on top of an all XFS filesystem since the beginning. The project
|
||||
has come to a point (actually nearly a year ago at the time of this
|
||||
writing) that this could actually be a reallity. However, as is
|
||||
the case with a great deal of programming/porting projects, the documentation
|
||||
for such task is not always as readily available or easy to follow
|
||||
as one might hope. This document is an attempt to remedy that situation.
|
||||
|
||||
</para>
|
||||
<para>
|
||||
The information contained in this document is based on messages
|
||||
from Jason Walker and Russell Cattelan taken from the XFS development
|
||||
mailing list, information gathered from various places on the SGI
|
||||
Open Source Development web site, and from my own experiences setting
|
||||
up such a system.
|
||||
</para>
|
||||
<para>
|
||||
Please feel free to email me at <email>ringram@gargoylecc.com</email> if you
|
||||
have any corrections or if any imformation/URLs/etc. is missing.
|
||||
The more feedback I get on this HOWTO the more helpful it will be
|
||||
for all.
|
||||
</para>
|
||||
<para>
|
||||
The latest version of this document can be found at
|
||||
<ulink url="http://www.gargoylecc.com/Linux+XFS-HOWTO/t1.html">
|
||||
Gargoyle Computer Consulting
|
||||
</ulink>.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2>
|
||||
<title>Copyright & Disclaimer</title>
|
||||
<para>
|
||||
This document is copyright(c) 2001 Russel Ingram and it is a
|
||||
FREE document. You may redistribute it under terms of the GNU General
|
||||
Public License.
|
||||
</para>
|
||||
<para>
|
||||
The information contained in this document is, to the best of
|
||||
Russel's knowledge, correct. However, the XFS Linux port is written
|
||||
by humans and thus, there is the chance that mistakes, bugs, etc.
|
||||
might happen from time to time.
|
||||
</para>
|
||||
<para>
|
||||
No person, group, or other body is responsible for any damage
|
||||
on your computer(s) and any other losses by using the information
|
||||
in this document. i.e.
|
||||
</para>
|
||||
<para>
|
||||
|
||||
</para>
|
||||
<para>
|
||||
<emphasis>
|
||||
THE AUTHOR IS NOT RESPONSIBLE FOR ANY DAMAGES INCURRED DUE TO
|
||||
ACTIONS TAKEN BASED ON THE INFORMATION IN THIS DOCUMENT.
|
||||
</emphasis>
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
<sect1>
|
||||
<title> Preparation for XFS Installation </title>
|
||||
<sect2>
|
||||
<title> Downloading the Linux 2.4.x-XFS Kernel Source </title>
|
||||
<para>
|
||||
Currently the only place to get the source code for the XFS enabled
|
||||
Linux kernel is straight from SGI's Open Source Development site
|
||||
via CVS.
|
||||
</para>
|
||||
<note>
|
||||
<title>Note</title>
|
||||
<para>two distinct trees are available:
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>linux-2.5-xfs: development tree</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>linux-2.4-xfs: stable bug fix only tree</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
My experience has been with the 2.4 tree, but I imagine everything
|
||||
will work the same with the development tree. Both trees are kept
|
||||
in sync with their respective mainline kernel tree at least to the
|
||||
point of major release numbers.
|
||||
</para>
|
||||
<para>
|
||||
Here are the steps to download the kernel source tree:
|
||||
|
||||
</para>
|
||||
<para>
|
||||
A. Normally the linux kernel source is installed in the /usr/src
|
||||
directory, so you should start off by switching to that directory.
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ cd /usr/src
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
B. Next, you should set the CVSROOT environment variable so that
|
||||
it points to the proper cvs server.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
If you are running sh, bash, ksh, etc...:
|
||||
<programlisting>
|
||||
$ export CVSROOT=':pserver:cvs@oss.sgi.com:/cvs'
|
||||
</programlisting>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
If you are running csh or tcsh:
|
||||
<programlisting>
|
||||
$ setenv CVSROOT :pserver:cvs@oss.sgi.com:/cvs
|
||||
</programlisting>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
If you plan on updating your kernel often (to keep up with the
|
||||
latest changes) you might want to put this in your login script.
|
||||
|
||||
</para>
|
||||
<para>
|
||||
C. Then log in to the cvs server.
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ cvs login (the password is "cvs")
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
This needs to be done only ONCE, not everytime you access CVS.
|
||||
|
||||
</para>
|
||||
<para>
|
||||
D. Now grab linux-2.4-xfs. The first time you will want to do
|
||||
something like:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ cvs -z3 co linux-2.4-xfs
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
After you have checked the code out, you can use:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ cvs -z3 update linux-2.4-xfs
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
to update your copy to the latest version from the CVS server.
|
||||
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2>
|
||||
<title> XFS Support as Modules or Compiled Into the Kernel? </title>
|
||||
<para>
|
||||
The option to build XFS support for the Linux kernel as modules
|
||||
is available and will work (or so I am told) with the help of an
|
||||
initial RAM disk and a couple of additions to the lilo configuration.
|
||||
I have not tried this (yet), so I will not include documentation
|
||||
on how this is done other than just to qoute from a message to the
|
||||
development mailing list from Russell Cattelan:
|
||||
</para>
|
||||
<blockquote>
|
||||
<attribution>
|
||||
<author>
|
||||
<firstname>Russell</firstname><surname>Cattelan</surname>
|
||||
</author>
|
||||
</attribution>
|
||||
<para>
|
||||
Actually running xfs as a module isn't very hard. in the
|
||||
directory cmd/xfs/misc there is a modified mkinitrd the will always
|
||||
generate a ram disk with pagebuf xfs_support and xfs.
|
||||
</para>
|
||||
<para>
|
||||
Once that is done just add the initrd line in lilo.conf AND
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
append = "ramdisk_size=25000"
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
The default size is 4096 which isn't nearly large enough to hold
|
||||
xfs.
|
||||
</para>
|
||||
<para>
|
||||
This is from my laptop.
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
punch[12:57am]-=>mount
|
||||
/dev/ide/host0/bus0/target0/lun0/part8 on / type xfs (rw,noatime)
|
||||
none on /proc type proc (rw)
|
||||
/dev/ide/host0/bus0/target0/lun0/part6 on /boot type ext2 (rw,noatime)
|
||||
none on /dev/pts type devpts (rw,mode=0620)
|
||||
/dev/ide/host0/bus0/target0/lun0/part1 on /mnt/windows type vfat (rw,nosuid,nodev,umask=0)
|
||||
/dev/ide/host0/bus0/target0/lun0/part9 on /blam type xfs (rw)
|
||||
|
||||
punch[12:57am]-=>lsmod
|
||||
Module Size Used by
|
||||
autofs 13180 1 (autoclean)
|
||||
usb-uhci 24918 0 (unused)
|
||||
usbcore 35339 0 [usb-uhci]
|
||||
3c59x 25149 1 (autoclean)
|
||||
maestro 29757 0 (unused)
|
||||
soundcore 6085 2 [maestro]
|
||||
vfat 13075 1 (autoclean)
|
||||
fat 37733 0 (autoclean) [vfat]
|
||||
xfs 447888 2
|
||||
xfs_support 13954 0 [xfs]
|
||||
pagebuf 39935 2 [xfs]
|
||||
|
||||
|
||||
image=/boot/vmlinuz-2.4.0-XFS-test13-pre4
|
||||
label=t13p4
|
||||
root=/dev/hda8
|
||||
initrd=/boot/initrd-2.4.0-XFS-test13p4.img
|
||||
append="ramdisk_size=25000"
|
||||
read-only
|
||||
</programlisting>
|
||||
</para>
|
||||
</blockquote>
|
||||
<para>
|
||||
It seems to me that compiling the support into the kernel would
|
||||
be much simpler, so that is how I am doing it at this point. I will
|
||||
try it as a module at a later time and add more detailed instructions
|
||||
then. If anyone has time to document this method before I get around
|
||||
to it please email it to me and I will include it with credit given
|
||||
where credit is due. :-)
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
<sect1>
|
||||
<title> Kernel Configuration and Installation </title>
|
||||
<sect2>
|
||||
<title>Configuring your kernel for XFS support</title>
|
||||
<note>
|
||||
<title>Note</title>
|
||||
<para>
|
||||
If you have never configured and compiled a new linux kernel
|
||||
you might consider reading the Linux Kernel HOWTO before doing this
|
||||
step. It can be found at the
|
||||
<ulink url="http://www.linuxdoc.org/HOWTO/Kernel-HOWTO.html">
|
||||
Linux Documentation Project (LDP)
|
||||
</ulink>
|
||||
or one of its mirrors.
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
After having downloaded the cvs source tree the actual kernel
|
||||
source will be in /usr/src/linux-2.4-xfs(-beta)/linux, so you should
|
||||
switch to that directory before running the make config command of
|
||||
your choice. The main things that must be included in your kernel
|
||||
to provide XFS support are "Page Buffer support" and (duh)
|
||||
"SGI XFS filesystem support." Both options are available
|
||||
in the "File systems" section of the kernel configuration.
|
||||
You will need to have "Prompt for development and/or incomplete
|
||||
code/drivers" selected under "Code maturity level options"
|
||||
for those options to be available to you. Optionally, you may also
|
||||
want to select "Enable XFS Debug mode" and "Enable
|
||||
XFS Vnode Tracing" under "SGI XFS filesystem support."
|
||||
These options may slow your XFS implementation some, but may be useful
|
||||
in tracing the cause of a crash if a crash occurs.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2>
|
||||
<title>Building the kernel and modules</title>
|
||||
<para>
|
||||
As with any kernel build, the following commands must be run
|
||||
to actually build the new kernel:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ make dep
|
||||
$ make bzImage
|
||||
$ make modules
|
||||
</programlisting>
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2>
|
||||
<title>Installing the new kernel and modules</title>
|
||||
<para>
|
||||
Again this is standard for any kernel installation:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ make modules_install
|
||||
$ cp arch/i386/boot/bzImage /boot/vmlinuz-2.4.0-XFS
|
||||
</programlisting>
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2>
|
||||
<title>Add a new entry to your lilo configuration and re-install lilo</title>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
$ vi /etc/lilo.conf
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
Add a new image section to your lilo.conf file similar to the
|
||||
following:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
image=/boot/vmlinuz-2.4.0-XFS label=xfs read-only root=/dev/hda2
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
The "root=" line should match the "root="
|
||||
line from the existing image sections in your lilo.conf file. Don't
|
||||
forget to run lilo when you're through editing lilo.conf to make
|
||||
the changes effective.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2>
|
||||
<title>Build and install the XFS utilities</title>
|
||||
<para>
|
||||
There are a number of tools that come with the XFS filesystem that allow
|
||||
you to build and manage your XFS filesystems that must be built as well.
|
||||
These tools are in the /usr/src/linux-2.4-xfs(-beta)/cmd/xfsprogs directory.
|
||||
</para>
|
||||
<note>
|
||||
<title>Note</title>
|
||||
<para>These tools rely on the /usr/lib/libuuid.a shared library. If you
|
||||
do not have this library installed you will need it in order for
|
||||
the XFS utilities to compile. You can find the rpm package for
|
||||
your version of Linux from <ulink url="http://www.rpmfind.net">Rpmfind.net</ulink> by searching for "/usr/lib/libuuid.a." The debian package that contains libuuid is uuid-dev. There will no doubt be other distributions that package this library in another place. A good way to find the correct package on those distributions is to search on the <ulink url="http://www.google.com/linux">Google Linux</ulink> search engine.
|
||||
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
Change to that directory:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ cd ../cmd/xfsprogs
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
Build and install the xfs utilities:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ make install
|
||||
</programlisting>
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2>
|
||||
<title>Boot the new kernel</title>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ reboot
|
||||
</programlisting>
|
||||
</para>
|
||||
<note>
|
||||
<title>Note</title>
|
||||
<para>
|
||||
Unless you changed the default label to boot in your lilo.conf
|
||||
file you will need to enter "xfs" at the "LILO Boot:"
|
||||
prompt in order to boot the new kernel image.
|
||||
</para>
|
||||
</note>
|
||||
</sect2>
|
||||
</sect1>
|
||||
<sect1>
|
||||
<title>Filesystem Migration</title>
|
||||
<para>
|
||||
The final part of this whole process is probably actually the
|
||||
trickiest and most dangerous as far as the possibility of losing
|
||||
your data goes. I strongly suggest that you make a complete backup
|
||||
of the system (or at least all important data) before attempting
|
||||
the migration to XFS. This part is also the most difficult to explain
|
||||
as there are probably hundreds of ways you can do this based on
|
||||
the set up of your existing filesystem. I will give you the basic
|
||||
commands for creating the new filesystems, try to give some pointers
|
||||
on how to go about shuffling filesystems, and in general just relay
|
||||
to you the way I went about migrating my own filesystems.
|
||||
</para>
|
||||
<sect2>
|
||||
<title>Migrating the / filesystem</title>
|
||||
<para>
|
||||
Probably the trickiest part of creating a fully XFS system is
|
||||
migrating the / filesystem since that is the system that supports
|
||||
the entire rest of the system and it cannot actually be unmounted
|
||||
while the system is running. If you have extra partitions that
|
||||
can be mounted as / then you will be able to do it something like
|
||||
this(I am using /dev/hda4 as the spare partition and /dev/hda2 as
|
||||
/ for this example):
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ mkfs -t ext2 /dev/hda4
|
||||
$ mkdir /mnt/temp
|
||||
$ mount -t ext2 /dev/hda4 /mnt/temp
|
||||
$ cd /
|
||||
$ tar lcf - .|(cd /mnt/temp; tar xpvf - )
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
Notice I have used tar here to copy the files from the / fs to
|
||||
the spare partition. Alternatively you could use cp -dpR, but if
|
||||
you use tar like I've shown here with the -l flag it will copy only
|
||||
files from within the / fs (i.e. if you have another partition mounted
|
||||
as /usr it won't copy those).
|
||||
</para>
|
||||
<para>
|
||||
The next step will be to change all references to /dev/hda2 to
|
||||
/dev/hda4 in /etc/fstab and in /etc/lilo.conf and run lilo. You'll
|
||||
then need to reboot the system again.
|
||||
</para>
|
||||
<para>
|
||||
After rebooting the system /dev/hda4 will be mounted as / and
|
||||
your original / filesystem (/dev/hda2) will not be mounted. You
|
||||
can now create the new XFS filesystem on /dev/hda2.
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ mkfs -t xfs /dev/hda2
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
Then mount the new xfs fs:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ mount -t xfs /dev/hda2 /mnt/temp
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
And copy the original / fs back to its original home:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ cd /
|
||||
$ tar lcf - .|(cd /mnt/temp; tar xpvf -)
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
Once again you will need to change all instances of /dev/hda4
|
||||
in /etc/fstab and /etc/lilo.conf and run lilo. You will also need
|
||||
to change the filesystem type for / in /etc/fstab. It should now
|
||||
look something like this:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
/dev/hda2 / xfs defaults 1 1
|
||||
</programlisting>
|
||||
</para>
|
||||
<note>
|
||||
<title>Note</title>
|
||||
<para>
|
||||
On some linux distributions the options given to the out-of-box
|
||||
fstab may be more in depth than just "defaults." For
|
||||
instance, on Debian systems they use "defaults,errors=remount-ro."
|
||||
The mount options are different for every filesystem with the exception
|
||||
of the keyword "defaults." Unless you know the specific
|
||||
XFS mount options you want you should stick with just the defaults
|
||||
option. In the Debian example given, the errors option is not available
|
||||
with XFS and will cause your filesystem not to mount.
|
||||
</para>
|
||||
<para>
|
||||
Additionally, filesystem labels are becoming more popular so you may see an
|
||||
entry in your fstab that looks something like this:
|
||||
<programlisting>
|
||||
LABEL=/ / ext2 defaults 1 1
|
||||
</programlisting>
|
||||
The easiest way to avoid problems is to simply replace the referenced label
|
||||
with the proper device file name (i.e. if /dev/hda1 is labeled / replace "LABEL=/"
|
||||
with "/dev/hda1").
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
Now reboot the system with the new xfs / filesystem.
|
||||
</para>
|
||||
<para>
|
||||
Of course there are a lot of other ways to accomplish the root
|
||||
filesystem migration and if you think you have a good one I would
|
||||
definitely like to hear it and will put it in this doc if it seems
|
||||
like a simpler way than what is here. I, myself, didn't have a
|
||||
spare partition to work with but had a CD burner so I burnt a cd
|
||||
of my root filesystem to mount as root while I created the new xfs
|
||||
/. In all cases, however, the basic commands for creating and mounting
|
||||
the new filesystem will be the same.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2>
|
||||
<title>Finishing up</title>
|
||||
<para>
|
||||
The last of the process is fairly simple and essentially the
|
||||
same process of swapping around partitions while making new filesystems
|
||||
as was done for /. I recommend that you do the rest of this process
|
||||
with the system in single user mode so you can unmount everything
|
||||
other than / and do all of the swapping without having to reboot
|
||||
a million times. You can boot to single user mode by either issueing
|
||||
a runlevel change command to the init process like so:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ telinit 1
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
or by rebooting and asking for single user mode at the Lilo prompt:
|
||||
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
LILO Boot: xfs single
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
This will boot the system and drop you into a root shell with
|
||||
no outside connections or virtual terminals so there is no chance
|
||||
of any of the filesystems being in use by other users or processes
|
||||
(causing them to be busy so you can't unmount them). Now you can
|
||||
mount the spare partition, as before, copy one of the remaining filesystems
|
||||
to be migrated onto it (you will probably have to remove the existing
|
||||
contents leftover from /), unmount the old filesystem, create the
|
||||
xfs filesystem on it, remount it as xfs, and copy the old filesystem
|
||||
back onto it. Lets say you have a /dev/hda3 partition mounted as
|
||||
/usr. The process would go something like this:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ mount -t ext2 /dev/hda4 /mnt/temp
|
||||
$ cd /usr
|
||||
$ tar lcf - .|(cd /mnt/temp; tar xpvf - )
|
||||
$ cd /mnt/temp
|
||||
$ umount /usr
|
||||
$ mkfs -t xfs /dev/hda3
|
||||
$ mount -t xfs /dev/hda3 /usr
|
||||
$ tar lcf - .|(cd /usr; tar xpvf - )
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
Don't forget to change the filesystem type in /etc/fstab for
|
||||
/usr to xfs.
|
||||
</para>
|
||||
<para>
|
||||
That's all there is to it. The rest of the filesystems to be
|
||||
migrated will work the same way, then you can reboot to full miltiuser
|
||||
mode and you've got your "Linux on Steroids!"
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
</article>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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 > 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 -> 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 -> 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 -> 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>
|
||||
|
|
@ -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 <broman@nosc.mil>".
|
||||
<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&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 ($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 $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 & 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 & Grant Edwards & Udo Munk for their work on Hercules.
|
||||
<item> Udo Munk for his work on serial mouse initialization & select.
|
||||
<item> Norman Bartek & Hal Snyder at Mark Williams Co. for their help
|
||||
with some bugs & 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>
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,262 @@
|
|||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
<title>MMBase Mini-HOWTO: Installation on Debian Woody
|
||||
|
||||
<author>Casper Joost Eyckelhof <tt/<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&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>
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,417 @@
|
|||
<!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
|
||||
<article>
|
||||
<articleinfo>
|
||||
<title>Using Term to Pierce an Internet Firewall mini-HOWTO</title>
|
||||
|
||||
<copyright><year>1996</year><holder>Barak Pearlmutter</holder></copyright>
|
||||
<copyright><year>2001</year><holder>David C. Merrill</holder></copyright>
|
||||
|
||||
<author>
|
||||
<firstname>Barak</firstname>
|
||||
<surname>Pearlmutter</surname>
|
||||
<affiliation>
|
||||
<address><email>bap@cs.unm.edu</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>David</firstname>
|
||||
<othername>C.</othername>
|
||||
<surname>Merrill</surname>
|
||||
<affiliation>
|
||||
<address>david -AT- lupercalia.net</address>
|
||||
</affiliation>
|
||||
</author>
|
||||
|
||||
<revhistory>
|
||||
<revision>
|
||||
<revnumber>1.1</revnumber>
|
||||
<date>2001-07-14</date>
|
||||
<authorinitials>dcm</authorinitials>
|
||||
<revremark>
|
||||
Cleaned up a bit, reorganized a bit, converted to DocBook SGML
|
||||
and relicensed under GFDL.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>1.0</revnumber>
|
||||
<date>1996-07-15</date>
|
||||
<authorinitials>pb</authorinitials>
|
||||
<revremark>Initial Release.</revremark>
|
||||
</revision>
|
||||
</revhistory>
|
||||
|
||||
<abstract>
|
||||
<para>
|
||||
This document explains how to use the <command>term</command> program
|
||||
to pierce a firewall from the inside, even without root privileges.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Term is an old program that almost no one uses anymore,
|
||||
because the 7-bit serial lines it is meant to cross are nowhere
|
||||
to be found anymore, and full IP ppp access is dirt cheap.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<important>
|
||||
<para>
|
||||
<emphasis role="strong">Archived Document Notice: </emphasis>
|
||||
This document has been archived by the LDP because it does not apply
|
||||
to modern Linux systems. It is no longer being actively maintained.
|
||||
</para>
|
||||
</important>
|
||||
</para>
|
||||
|
||||
</abstract>
|
||||
|
||||
</articleinfo>
|
||||
|
||||
<sect1 id="preface">
|
||||
<title>Preface</title>
|
||||
|
||||
<sect2 id="disclaimer">
|
||||
<title>Disclaimer</title>
|
||||
|
||||
<para>
|
||||
While every precaution has been taken in the preparation of this document,
|
||||
the Linux Documentation Project and the author(s) assume no responsibility
|
||||
for errors or omissions, or for damages resulting from the use of the
|
||||
information contained herein.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="license">
|
||||
<title>License</title>
|
||||
|
||||
<para>
|
||||
This document is made available under the terms of the
|
||||
<ulink url="http://www.gnu.org/copyleft/fdl.html"><citetitle>GNU Free Documentation License (GFDL)</citetitle></ulink>,
|
||||
which is hereby incorporated by reference.
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="introduction">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>
|
||||
The <command>term</command> program is usually used to provide host-to-host services
|
||||
over a modem or serial line.
|
||||
|
||||
However, sometimes it is useful to establish a term
|
||||
connection between two machines that communicate via telnet.
|
||||
The most
|
||||
interesting example is connecting two hosts which are
|
||||
separated by ethernet firewalls or SOCKS servers. Such firewalls
|
||||
provide facilities for establishing a telnet connection through the
|
||||
firewall, typically by using the SOCKS protocol, to allow inside
|
||||
machines to get connections out, and requiring outside users to telnet
|
||||
first to a gateway machine which requires a one-time password. These
|
||||
firewalls make it impossible to, for instance, have X clients on an
|
||||
inside machine communicate with an X server on an outside machine.
|
||||
But, by setting up a term connection, these restrictions can all be
|
||||
bypassed quite conveniently, at the user level.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="basics">
|
||||
<title>The Basic Procedure</title>
|
||||
|
||||
<para>
|
||||
Setting up a term connection over a telnet substrate is a two-phase
|
||||
process. First your usual telnet client is used to set up a telnet
|
||||
connection and log in. Next, the telnet client is paused and control
|
||||
of the established telnet connection is given to term.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="details">
|
||||
<title>Detailed Directions</title>
|
||||
|
||||
<para>
|
||||
First, from a machine inside the firewall, telnet to a target machine
|
||||
outside the firewall and log in.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Unless you are under linux and will be using the proc filesystem (see
|
||||
below) make sure your shell is an sh style shell. Ie if your default
|
||||
shell is a csh variant, invoke telnet by:
|
||||
</para>
|
||||
|
||||
<para><screen>setenv SHELL /bin/sh; telnet machine.outside</screen></para>
|
||||
|
||||
<para>
|
||||
After logging in, on the remote (outside) machine invoke the command:
|
||||
</para>
|
||||
|
||||
<para><screen>term -r -n off telnet</screen></para>
|
||||
|
||||
<para>
|
||||
Now break back to the telnet prompt on the local (inside) machine,
|
||||
using <literal>^]</literal> or whatever, and use the telnet shell escape command
|
||||
<literal>!</literal> to invoke term:
|
||||
</para>
|
||||
|
||||
<para><screen>telnet> ! term -n on telnet >&3 <&3</screen></para>
|
||||
|
||||
<para>
|
||||
That's it!
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you have a variant telnet, you might have to use some other file
|
||||
descriptor than 3; easy to check using strace. But three seems to
|
||||
work on all bsd descendent telnet clients I've tried, under both SunOS
|
||||
4.x and the usual linux distributions.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Some telnet clients do not have the ! shell escape command. Eg the
|
||||
telnet client distributed with Slackware 3.0 is one such client. The
|
||||
sources that the Slackware telnet client is supposedly built from
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<ulink url="ftp://ftp.cdrom.com:/pub/linux/slackware-3.0/source/n/tcpip/NetKit-B-0.05.tar.gz">
|
||||
<citetitle>ftp://ftp.cdrom.com:/pub/linux/slackware-3.0/source/n/tcpip/NetKit-B-0.05.tar.gz</citetitle></ulink>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A simple solution is therefore to
|
||||
obtain these sources and recompile them. This unfortunately is a task
|
||||
I have had no luck with. Plus, if you are running from inside a SOCKS
|
||||
firewall, you will need a SOCKSified telnet client anyway. To that
|
||||
end, I was able to compile a SOCKSified telnet client from:
|
||||
</para>
|
||||
|
||||
<para><ulink url="ftp://ftp.nec.com/pub/security/socks.cstc/socks.cstc.4.2.tar.gz">
|
||||
<citetitle>ftp://ftp.nec.com/pub/security/socks.cstc/socks.cstc.4.2.tar.gz</citetitle></ulink>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
or, if you're outside the USA,
|
||||
</para>
|
||||
|
||||
<para><ulink url="ftp://ftp.nec.com/pub/security/socks.cstc/export.socks.cstc.4.2.tar.gz">
|
||||
<citetitle>ftp://ftp.nec.com/pub/security/socks.cstc/export.socks.cstc.4.2.tar.gz</citetitle></ulink>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Alternatively, under linux kernels up to 1.2.13, you can pause the
|
||||
telnet with <literal>^]^z</literal>, figure out its pid, and invoke:
|
||||
</para>
|
||||
|
||||
<para><screen>term -n on -v /proc/&,t;telnetpid>/fd/3 telnet</screen></para>
|
||||
|
||||
<para>
|
||||
This doesn't work with kernels after 1.3.x, which closed some
|
||||
mysterious security hole by preventing access to these fd's by
|
||||
processes other than the owner process and its children.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="termsockets">
|
||||
<title>Multiple Term Sockets</title>
|
||||
|
||||
<para>
|
||||
It is a good idea to give the term socket an explicit name.
|
||||
This is the <literal>telnet</literal>; argument in the invocations
|
||||
of term above.
|
||||
Unless you have the TERMSERVER environment variable set to telnet as
|
||||
appropriate, you invoke term clients with the -t switch,
|
||||
e.g., <literal>trsh -t telnet</literal>.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="termrc.telnet">
|
||||
<title>The <<filename>˜/.term/termrc.telnet</filename> Init File</title>
|
||||
|
||||
<para>
|
||||
I have checked line clarity using linecheck over this medium.
|
||||
I expected it to be completely transparent, but it is not.
|
||||
However, the only bad character seems to be 255.
|
||||
The <filename>˜/.term/termrc.telnet</filename> I use
|
||||
(the <filename>.telnet</filename> is the name of the term connection, see above)
|
||||
contains:
|
||||
</para>
|
||||
|
||||
<para><screen>baudrate off
|
||||
escape 255
|
||||
ignore 255
|
||||
timeout 600</screen></para>
|
||||
|
||||
<para>
|
||||
Perhaps it could be improved by diddling,
|
||||
I am getting a throughput of only about 30k cps over
|
||||
a long-haul connection through a slow firewall.
|
||||
Ftp can move about 100k cps over the same route.
|
||||
A realistic baudrate might avoid some timeouts.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="direction">
|
||||
<title>Direction</title>
|
||||
|
||||
<para>
|
||||
Obviously, if you are starting from outside the firewall and zitching
|
||||
in using a SecureID card or something, you will want to reverse the
|
||||
roles of the remote vs local servers given above. (If you don't
|
||||
understand what this means, perhaps you are not familiar enough with
|
||||
term to use the trick described in this file responsibly.)
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="security">
|
||||
<title>Security</title>
|
||||
|
||||
<para>
|
||||
This is not much more of a vulnerability than the current possibility
|
||||
of having a telnet connection hijacked on an unsecured outside
|
||||
machine. The primary additional risk comes from people being able to
|
||||
use the term socket you set up without you even being aware of it. So
|
||||
be careful out there. (Personally, I do this with an outside machine
|
||||
I know to be pretty secure, namely a linux laptop I maintain myself
|
||||
that does not accept any incoming connections.)
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Another possibility is to add
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<screen>socket off</screen>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
to the remote <filename>˜/.term/termrc.telnet</filename> file, or
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<screen>add "-u off"</screen>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
to the invocation of term.
|
||||
This prevents the socket from being hijacked from the remote end,
|
||||
with only a minor loss of functionality.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="telnet">
|
||||
<title>Telnet Mode</title>
|
||||
|
||||
<para>
|
||||
Be sure the remote telnetd is not in some nasty seven-bit mode.
|
||||
Or if it is, you have to tell term about it when you invoke term,
|
||||
by adding the <literal>-a</literal> switch at both ends.
|
||||
(I sometimes use <literal>>^] telnet> set outbin</literal> or
|
||||
<literal>set bin</literal>, or invoke telnet with a <literal>-8</literal> switch
|
||||
to put the connection into eight-bit mode.)
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="bugs">
|
||||
<title>Bugs and Term Wish List</title>
|
||||
|
||||
<para>
|
||||
The <command>linecheck</command> program has some problems checking telnet connections
|
||||
sometimes. This is sometimes because it doesn't check the return code
|
||||
of the <function>read()</function> call it makes. For network connections,
|
||||
this call to <function>read()</function> can return <literal>-1</literal>
|
||||
with an <literal>EINTR</literal> (interrupted) or
|
||||
<literal>EAGAIN</literal> (try again) error code.
|
||||
Obviously this should be checked for.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
There are a number of features that could ease the use of term over
|
||||
telnet. These primarily relate to an assumption that influenced the
|
||||
design of term, namely that the connection is low bandwidth, low
|
||||
latency, and somewhat noisy.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A telnet connection is in general high bandwidth, high latency, and
|
||||
error free. This means that the connection could be better utilized
|
||||
if (a) the maximum window size was raised, well above the limit
|
||||
imposed by term's <literal>N_PACKETS/2=16</literal>,
|
||||
(b) there was an option to turn off sending and checking packet checksums,
|
||||
and (c) larger packets were permitted when appropriate.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Also, to enhance security, it would be nice to have a term option to
|
||||
log all connections through the socket it monitors to a log file, or
|
||||
to <literal>stderr</literal>, or both. This would allow one to see if one's term
|
||||
connection is being subverted by nasty hackers on the outside insecure
|
||||
machine.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="tricks">
|
||||
<title>Tricks That Do Not Seem to Work</title>
|
||||
|
||||
<para>
|
||||
Some telnet clients and servers agree to encrypt their communications,
|
||||
to prevent eavesdropping on the connection. Unfortunately, the hack
|
||||
used above (using the network connection that the telnet client has
|
||||
set up while the telnet client is idle) won't work in that case.
|
||||
Instead, one really must go through the telnet client itself, so it
|
||||
can do its encryption. It seems like that requires a simple hack to
|
||||
the telnet client itself, to add a command that runs a process with
|
||||
its <literal>stdin</literal> and <literal>stdout</literal> are connected
|
||||
to the live telnet connection.
|
||||
This would also be useful for various bots, so perhaps someone has
|
||||
already hacked it up.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="resources">
|
||||
<title>Related Resources</title>
|
||||
|
||||
<para>
|
||||
A vaguely related trick is to SOCKSify one's Term library.
|
||||
Details, including patches to SOCKS, are available from
|
||||
Steven Danz <ulink url="mailto:danz@wv.mentorg.com"><citetitle>danz@wv.mentorg.com</citetitle></ulink>.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="acknowledgements">
|
||||
<title>Acknowledgments</title>
|
||||
|
||||
<para>
|
||||
Thanks for valuable suggestions from:
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Gary Flake <ulink url="flake@scr.siemens.com"><citetitle>flake@scr.siemens.com</citetitle></ulink></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Bill Riemers <ulink url="bcr@physics.purdue.edu"><citetitle>bcr@physics.purdue.edu</citetitle></ulink></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Greg Louis <ulink url="glouis@dynamicro.on.ca"><citetitle>glouis@dynamicro.on.ca</citetitle></ulink></para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
</sect1>
|
||||
|
||||
</article>
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -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/˜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 <=2.0.33
|
||||
& 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 <=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 <=2.0.33 & 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 <=2.0.34 & 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 "Introduction and Disclaimer", 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, & 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") 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 udmageneric'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 & 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/KernelHOWTO.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 UDMAcapable drive interfaces built into motherboards. They use
|
||||
the standard IDE I/O ports and so are fully usable at the slower nonUDMA
|
||||
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/˜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
|
||||
& 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>
|
||||
|
|
@ -0,0 +1,360 @@
|
|||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
|
||||
<title>The VPN HOWTO
|
||||
<author>Arpad Magosanyi <mag@bunuel.tii.matav.hu> 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' -> -o 'BatchMode yes' by Zot O'Connor <zot@crl.com>
|
||||
|
||||
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 <zot@crl.com> 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: >= 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 ˜slave/.ssh, and the second is ˜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,'˜' and '^Z'. You should have the master's prompt now, and kill %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 (˜) 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: <On most systems, setting the escape character to ``none'' will also make the session transparent even if a tty is used.> 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 <http://www.xarius.demon.co.uk/software/posix6/>. 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>
|
||||
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue