# Distribution Roadmap: What's Where in Linux FreeS/WAN

This file is a guide to the locations of files within the FreeS/WAN distribution. Everything described here should be on your system once you download, gunzip, and untar the distribution.

This distribution contains two major subsystems

KLIPS
  the kernel code
Pluto
  the user-level key-management daemon

plus assorted odds and ends.

## Top directory

The top directory has essential information in text files:

README
  introduction to the software
INSTALL
  short experts-only installation procedures. More detalied procedures are in installation and configuration HTML documents.
BUGS
  major known bugs in the current release.
CHANGES
  changes from previous releases
CREDITS
  acknowledgement of contributors
COPYING
  licensing and distribution information

## Documentation

The doc directory contains the bulk of the documentation, most of it in HTML format. See the index file for details.

## KLIPS: kernel IP security

KLIPS is KerneL IP Security. It lives in the klips directory, of course.

klips/doc
  documentation
klips/patches
  patches for existing kernel files
klips/test
  test stuff
klips/utils
  low-level user utilities
klips/net/ipsec
  actual klips kernel files
klips/src
  symbolic link to klips/net/ipsec

  The "make insert" step of installation installs the patches and makes a symbolic link from the kernel tree to klips/net/ipsec. The odd name of klips/net/ipsec is dictated by some annoying limitations of the scripts which build the Linux kernel. The symbolic-link business is a bit messy, but all the alternatives are worse.

klips/utils
  Utility programs:

  eroute
    manipulate IPSEC extended routing tables
  klipsdebug
    set Klips (kernel IPSEC support) debug features and level
  spi
    manage IPSEC Security Associations
  spigrp
    group/ungroup IPSEC Security Associations
  tncfg
    associate IPSEC virtual interface with real interface

  These are all normally invoked by ipsec(8) with commands such as

              ipsec tncfg arguments

  There are section 8 man pages for all of these; the names have "ipsec_" as a prefix, so your man command should be something like:

              man 8 ipsec_tncfg

## Pluto key and connection management daemon

Pluto is our key management and negotiation daemon. It lives in the pluto directory, along with its low-level user utility, whack.

There are no subdirectories. Documentation is a man page, pluto.8. This covers whack as well.

## Utils

The utils directory contains a growing collection of higher-level user utilities, the commands that administer and control the software. Most of the things that you will actually have to run yourself are in there.

ipsec
  invoke IPSEC utilities

  ipsec(8) is normally the only program installed in a standard directory, /usr/local/sbin. It is used to invoke the others, both those listed below and the ones in klips/utils mentioned above.

auto
  control automatically-keyed IPSEC connections
manual
  take manually-keyed IPSEC connections up and down
barf
  generate copious debugging output
look
  generate moderate amounts of debugging output

There are .8 manual pages for these. look is covered in barf.8. The man pages have an "ipsec_" prefix so your man command should be something like:

            man 8 ipsec_auto

Examples are in various files with names utils/*.eg

## Libraries

### FreeS/WAN Library

The lib directory is the FreeS/WAN library, also steadily growing, used by both user-level and kernel code.
It includes section 3 man pages for the library routines.

### Imported Libraries

#### LibDES

The libdes library, originally from SSLeay, is used by both Klips and Pluto for Triple DES encryption. Single DES is not used because it is insecure.

Note that this library has its own license, different from the GPL used for other code in FreeS/WAN.

The library includes its own documentation.

#### GMP

The GMP (GNU multi-precision) library is used for multi-precision arithmetic in Pluto's key-exchange code and public key code.

Older versions (up to 1.7) of FreeS/WAN included a copy of this library in the FreeS/WAN distribution.

Since 1.8, we have begun to rely on the system copy of GMP.