Patch title: Release 85 bulk changes
Abstract:
File: /pliant/fullpliant/index.page
Key:
    Removed line
    Added line
title "FullPliant operating system"

header "Overview"

  header "FullPliant goals"

    list
      item [Make it easy to keep a set of computers up and properly running (no local administration, very few remote administration).]
      item [Make it easy to automat repetitive tasks.]
      item [Does not care about fun.]

  header "What's different when running FullPliant"

    [FullPliant is a three layers operating system.] ; eol
    [There is:]
    list
      item [the Linux kernel]
      item [the FullPliant server]
      item [the embedded computer (a Debian distribution + many applications compiled from source)]
    [On the other hand, in a classical system, there are only two layers (kernel and everything else).]

  para
    [These are some interesting properties about FullPliant layers:]
    list
      item [the FullPliant server layer is small (10 MB) and very consistent (written in a single language, with all configuration files stored as Pliant databases, most of these beeing organization wide), so it's easier to maintain.]
      item [the FullPliant server layer runs as a single process, so an automation task that involves several services (HTTP, database, backup, ...) will need no glue code.]
      item [the embedded computer layer is completely generic (you can have the same one on all your computers even if they have very different hardware and services because all configuration files will be overwritten at boot time by Pliant scripts, according to FullPliant configuration database content), so if something goes wrong, you can upload the tarball and the all embedded system will be reinstalled automatically.]
      item [the embedded computer layer is installed in /debian/, not at root, so it is a bit less likely to disturb the FullPliant server.]
      item [the embedded computer is a set of Debian potato packages for low level tools and some now stable applications, and compiled from source by Pliant installation tool for bleeding edge applications where the latest is the best.]

  para
    [The other different think with FullPliant is that each computer definition is a record (a set of set of set of stings in facts) in the general computers databases, and the all computer files tree can be generated unattended from the informations in that record. ]
    [You could think about this record as a central definition about the computer details just like the 'registry' in another well known system. ]
    [Also there is still a big difference: ]
    [You don't set each entry of the computer definition one after the other. There is a simple and easily extendable set of 'macros' that enables you to provide more meaningfull (I mean much shorter) declaration that will be expanded to the full declaration thanks to the macros. ]
    [Here is an example about ] ; link "what you fill" "doc/sample_computer.html" ; [ and ] ; link "the real content it generates" "doc/sample_settings.html" ; [ after expanding the macros.]
    eol
    [So, if you have quite a few computers, this mechanism enables you to install or reinstall efficiently any of your systems (and clean it in case it starts getting crazy, any real world administrator probably understanding what I mean here) even if all these systems are not all the same (what a raw file systems or sectors copy does not allow).]

  para
    [Lastly, if you look at FullPliant from a Linux perspective, then you can think about it as Linux without Unix, since all the basic services (DNS, HTTP, SMTP and so on) are Pliant applications, not Unix standard ones, and the all computer can be configured through a simple HTML browser. ]


  header "What services does a FullPliant system provides"

    header "Provided through the FullPliant server layer"

      list
        item [A Pliant boot script that will check disks, start networking and so on]
        item [Pliant HTTP server]
        item [Pliant FTP server]
        item [Pliant DNS server]
        item [Pliant SMTP server]
        item [Pliant POP3 server]
        item [Pliant web mail]
        item [Pliant backup system (engraves CDs and keeps details in a database)]
        item [Pliant forum]
        item [The server status board (enables you to see the load, shutdown the server and so on)]
        item [Pliant files browser]
        item [Pliant database engine]
        item [Pliant interpreter]
        item [Pliant secured proxy (provides secured access to a remote Pliant HTTP server)]
        item [FullPliant installation tool (including computers definition database, and easy software RAID1 installation on low end PCs)]
  
    header "Provided through the embedded computer layer"

      list
        item [X11]
        item
          [Most advanced web browsers:]
          list
            item [Netscape 4]
            item [Mozilla]
            item [Galeon]
            item [Konqueror]
        item
          [HTML editor:]
          list
            item (link "Quanta" "http://quanta.sourceforge.net/")
        item
          [Office suites:]
          list
            item [Koffice (Kword, Kspread)]
            item [Gnome office (Abiword, Gnumeric)]
            item [StarOffice]
        item
          [Many drawing tools:]
          list
            item [Gimp imaging software]
            item [Sketch vector drawing]
            item [Sodipodi SVG editor]
            item [Dia diagram editing software]
            item [...]
        item
          [File managers:]
          list
            item [KDE Konqueror]
            item [TkDesk]
        item
          [Text editors:]
          list
            item [KDE Kate]
            item [TkDesk editor]
        item
          [Convertion utilities]
          list
            item [Word (tm) -> HTML]
            item [Excel (tm) -> HTML]
            item [HTML -> PostScript]
            item [PostScript -> PDF]
        item [Printing system based on GhostScript and Gimp print]
        item [Files sharing through NFS, Samba and Netatalk, administred from FullPliant (please notice that you can still share files without these services through HTTP or FTP).]
        item [Bash shell]
        item [Development tools]


  header "How to install a FullPliant computer (overview)"

    para
      [First, you have to specify all the computer configuration in a form. ]
      [The key difference between FullPliant and other installation systems is that with FullPliant, you specify most configuration details (all is the target) at installation time: when the computer boots for the first time, it should be up and running, fully configured. ]
      [Here is the ] ; link "sample definition" "doc/sample_computer.html" ; [ of the server servicing http://pliant.cx/ site.]

    [Then, you select one of the three possible installation methods:]
    list
      item [Install from a single floppy, through the network (recommanded)]
      item
        [Install from CD (recommanded only for recovery and for Laptops. ]
        note "Why ?"
          [Because the CD is different for each computer since it contains all details about the computer configuration.] ; eol
          [For Laptops, you can hardly use the through the network installation because it requires PCMCIA which is not available on the FullPliant boot floppy. ]
          [One can still use a DLink like parallel port ethernet interface which does not requires PCMCIA, but it's painfully slow and not very reliable.]
        [)]
      item [Install from another Linux or FullPliant system on another partition]

    para
      [When you install through the network (or from a CD), you need to define two computers: ]
      [one is the real target computer, and one is a middle computer definition that will be used to boot the target computer in a special mode that will run the installation program.]


  header "What hardware do I need to run FullPliant"

     para
       [Let's start by clarifying:]
       list
         item
           [A 'server' computer is something that runs Pliant services (HTTP, SMTP, ....) and that you access remotely: it may have no screen and no keyboard. ]
           note "(extra details)"
             [With FullPliant, a 'server' computer can run without the embedded computer, except if it needs to provide files sharing services.] ; eol
         item
           [A 'client' computer is something you sit in front of, and use the mouse an keyboard to access the web browser or desktop softwares. ]
           note "(extra details)"
             [With FullPliant, a 'client' computer is always also a 'server' computer.]

     para
       [What hardware do I need to run] ; eol
       note "a tiny server"
         [For a tiny FullPliant server computer, you need a PC with:]
         list
           item [i386 compatible processor(s)]
           item [16 MB or more memory (64 MB if you need an embedded computer in order to provide files sharing).]
           item [100 MB or more hard disk (1 GB if you need an embedded computer in order to provide files sharing)]
         para [Using 2 IDE disks, and an UPS, is very much recommended in order to provide RAID 1, even on a tiny server.]
         para [If you have only 1 IDE disk, using an IDE engraver for backups (connected on the second IDE channel) is a very good idea, but if you have 2 IDE disks in order to provide RAID 1, then the IDE engraver will not be reliable, so you need an SCSI CD engraver.]
       eol
       note "a medium server"
         [For a medium FullPliant server computer, you need a PC with:]
         list
           item [700 Mhz pentium III or better i386 compatible processor (a dual processor is much better)]
           item [512 MB memory or even more (memory is now cheap)]
           item [2 multi gigabytes 10000 rpms or more, ultra 2 or more SCSI disks (Tekram provides very reliable Ultra LVD SCSI controlers with two channels)]
           item [a SCSI CD engraver on the second channel of the SCSI controler]
           item [an UPS]
       eol
       note "a client computer"
         [For a client FullPliant computer, you need a PC with:]
         list
           item [pentium class or better i386 compatible processor(s)]
           item [64 MB or more memory]
           item [1 GB or more hard disk]
           item [a XFree86 3 compatible graphic card (an old ATI or S3 should be ok).]

     para
       italic [If I want 10 users to use a Pliant database at once, or 10 users to download through FTP at onces, how powerfull a server do I need ?] ; eol
       [There is no clear answer, but from what I've notice an old 90 Mhz pentium should be abble to service many users at onces (probably much more than 10). ]
       [What you will see most if your processor is slow is how long it will be to boot or restart Pliant services. ]
       [Here are some approximative ]
       note "numbers"
         table columns 2 enlarge 0
           cell header [Processor] ; cell header [Approximative time to boot FullPliant]
           cell [i486 sx] ; cell [about 1 hour]
           cell [pentium 90] ; cell [something like 10 minutes]
           cell [pentium III 700Mhz] ; cell [about 1 minute]
       [.]


header "Step by step installation"


  header "Before starting: creating the file:/fullpliant/ tree"

    para
      [In order to install FullPliant, you need a running Linux or FullPliant system. You don't need to have Linux installed on the computer you want to install FullPliant on, but do need to have a computer (this one or another) installed with Linux or FullPliant. ]
      [The main reason is that FullPliant installation tool will build a custom Linux kernel for the target computer, so it needs a working Linux or FullPliant system to run the kernel 'make' script.]

    para
      [First and once for all, you have to build the] ; fixed [ file:/fullpliant/ ] ; [ tree in your computer. ]
      [It would be easier if you could download it all at once from Pliant web site, but it's too big for the 128 Kbps line linking http://pliant.cx/ site, so you will have to build it locally through downloading (most is done automatically by FullPliant installation tool) from various sites.] ; eol

    list
      item
        [Download a sample ] ; link "computers definition database" "http://pliant.cx/archive/computer.pdb" ; [ and store it in] ; fixed [ security:/computer.pdb ]
        note "(extra details)"
          [If you don't know where] ; fixed [ security:/ ] ; [directory is on your system, just type in:]
          listing
            pliant module /pliant/admin/file.pli command 'console file_os_name:"security:/" eol'
      item
        [Download the ] ; link " custom part of thefile:/fullpliant/ tree" "http://pliant.cx/archive/fullpliant.tgz" ; [ and unpack it at] ; fixed [ file:/]
      item
        [Download a ] ; link "Linux 2.2.19 kernel" "ftp://ftp.uk.kernel.org/pub/linux/kernel/v2.2/linux-2.2.19.tar.gz" ; [ and store it in] ; fixed [ file:/fullpliant/kernel/src/]
      item
        [Download a ] ; link "PCMCIA packages 3.1.25" "http://pcmcia-cs.sourceforge.net/ftp/OLD/pcmcia-cs-3.1.25.tar.gz" ; [ and store it also in] ; fixed [ file:/fullpliant/kernel/src/]
      item
        [If you want RAID support, you also need to download ] ; link "RAID patch" "http://www.kernel.org/pub/linux/kernel/people/mingo/raid-patches/raid-2.2.19-A1" ; [ and store it in] ; fixed [ file:/fullpliant/kernel/src/]

    para
      small [NB:] ; [ If you already have a kernel source tree, but not the right one, as an example linux-2.2.17.tar.gz, then you need only to download patch-2.2.18.gz and patch-2.2.19.gz and put everything in] ; fixed [ file:/fullpliant/kernel/src/ ] ; [ since FullPliant installation script knows how to apply patches.]
      

  header "First step: defining the target computer configuration"

    para
      [First start the Pliant HTTP server, log as administrator, and select 'Configuring the server' 'Computers' ]
      note "(how to start the HTTP server)"
        [If you don't know how to the the HTTP server and log as administrator, the simplest is probably to just type in:]
        listing
          pliant module /pliant/protocol/http/server.pli command 'http_server configure'
        [and connect to it through typing] ; fixed [ http://localhost/ ] ; [in your web browser,] ; eol
        [or (if you already have an HTTP server running on port 80):]
        listing
          pliant module /pliant/protocol/http/server.pli command 'http_server port 8080 configure'
        [and connect to it through typing] ; fixed [ http://localhost:8080/]

    para
      [Now watch the declaration of a fiew sample computers through selecting 'Configuring the server' then 'Computers' buttons, and declare your own one as a copy of one of these.] ; eol
      list
        item
          fixed [server5.heliogroup.fr ] ; [is a simple server definition (no embedded computer so no keyboard and screen).]
        item
          fixed [server1.heliogroup.fr ] ; [is a fairly complex server definition including RAID disks, two network cards, ISDN bridges and files sharing.] ; eol
        item
          fixed [hubert.heliogroup.fr ] ; [is my Inspiron laptop definition including an embedded computer and remote printing.] ; eol

    para
      [As specifyed in the overview, a computer definition is a set of set of set of strings, so you can think about it as a set of tables, where the first level would be the table id, the second level would be the row id, and the third level would be the filed id.] ; eol
      [Now remember that with FullPliant you will not fill the entire computer definition one entry after the other (you can view all settings about a computer through pressing 'Display settings' or 'Display raw settings database' button). You rather use a set of macros that will define many entries at once.]     
    para
      [In a computer definition, the 'Component' column enables you to select one of the macros ]
      [ (You can get a list of all availables macros through selecting 'defining computer components' link in the computers list page).] ; eol
      [The 'Instance' column enables you to specify the row id to apply the macro on. ]
      [As an example, if you have several routing entries to define, you will declare several 'network/route' definitions, each of them with a different 'Instance' id.] ; eol
      [Lastly, each time you've selected a macro and filled 'Instance' cell, you should press the 'Recompute settings' to get all the computer definition recomputed, and definitions created or destroyed, BEFORE filling extra parameters.]

    para
      [If you are installing your first FullPliant system, and have downloaded the] ; fixed [ file:/fullpliant/ ] ; [ parts as explained in the 'Before starting' part, you have to press the 'Upgrade Debian packages list' to get Debian packages list downloaded (and restart if the download process fails).] ; eol
      [Then you have to press the 'Recompute settings' button to get FullPliant select the Debian packages it requires, ]
      [and finally press 'Download Debian packages' to get these packages downloaded. ]
      [This will take a very long time if you have a slow or unreliable connection, an you should try again until FullPliant install program does not attempt to download any more.]

    para
      italic [I see no cell to specify the network IP address in the sample computers definition ?] ; eol
      [You have to set the name -> IP assignment in 'Configure the server' 'Names'. Since this assignment is site wide, it's not part of the computer definition.]


  header "Second step: build the target system tarball"

    [Just press the 'Build target system archive' button.] ; eol

    list
      item [It will take some time if the Linux kernel needs to be built (a kernel is only built once for any given set of settings).]
      item [Generating a long site key takes time, and is required only once for each target computer.]
      item [Building the embedded computer takes an awfully long time (C compiling is slow), and needs to download files from the Internet, but is required only once for all your computers.]
    [on the other hand, rebuilding a tarball when none of these is required is only a few seconds.]

    table columns 1
      cell color lsh 80 15 0
      cell color (color hsl 0 15 75)
        [If you are a Linux hacker, remember that this step will overwrite some] ; fixed [ file:/usr/src/linux*/ ] ; [ directories, so make backups !]


  header "Third step: build the intermediate system"

    [The intermediate system is the system you are going to boot on the target computer to get the install program running, and ask it to partition, format, then unpack the target system tarball.] ; eol

    [The intermediate system definition should be site wide (you should use the same one for all your target computers).] ; eol
    [If you are installing from the network, you should use 'install' computer definition as a sample.] ; eol
    [If you are installing from a CD, you should use 'recover' computer definition as a sample.] ; eol

    para
      [Please notice that (I gess that) you need Grub to be available in your system (you don't need your system to boot through Grub, but simply have Grub package installed).]

    header "Installing from the network"

      para
        [You should first adjust adminsistrator account rights so that you will be abble to log on the intermediate system HTTP server with administrator rights. ]
        [As a example, see the line 3 on ] ; link "my account definition" "doc/administrator.html" ; [.]

      para
        [Then, press 'Build the tree for installing through NFS' in the intermediate computer definition. ]
        [The intermediate computer will be built in your] ; fixed [ file:/export/diskless/*/ ] ; [ tree] ; eol
      para
        [... and finally press the 'and the boot floppy' button.]
      
    header "Installing from a CD"

      [Press 'Engrave a recovery CD' in the intermediate computer definition. ]
      [A recovery CD is also an installation CD.]


  header "Last step: truely installing the target system"

    header "Installing from the network"

      para
        [First, check that NFS server is running on your computer, and that ] ; fixed [ /export/diskless/ ] ; [ is properly exported.] ; eol
        [Then boot thet target system from the floppy you've built.] ; eol
        [If the floppy is ok, you should see Grub menu appear after a few seconds, ]
        [and if the network settings are right you should get 'Lauching Pliant boot script' message right after the Linux kernel boot messages.]

      para
        [Connect to the intermediate system HTTP server, log as administrator, select 'Configuring the server' 'Computers', and select the target computer definition.] ; eol
        [Now you can press the 'Partition ...' buttons to get your disks partitioned if required.] ; eol
        [Then you can press the 'Format ...' buttons to get your partitions formated (and declared for the RAID ones) if required.] ; eol
        [Then you should press 'Install the system'] ; eol
        [and finally 'Make the new system bootable'.]

    header "Installing from a CD"

      [When the system boots, you only have to provide one word form the keyboard, which is the installation level you want.]

      table columns 1
        cell color lsh 80 15 0
        cell color (color hsl 0 15 75)
          [When you boot from the FullPliant CD, if you answer nothing withing 5 minutes, recovery will be started automatically.]


header "Post install"

  header "Customizing"

    para
      [You should create a] ; fixed [ /custom/] ; italic [domain] ; fixed [/] ; italic [computer] ; fixed [/fullpliant.page ] ; [ module to provide a customized per computer home page. ]
      [Here is a ] ; link "sample" "doc/fullpliant.page" options "filter_ascii" ; [ one.] 
    para
      [You can also create a] ; fixed [ /custom/] ; italic [domain] ; fixed [/] ; italic [computer] ; fixed [/run.pli ] ; [ module so that some HTTP pages will be compiled immediately when the HTTP server starts. ]
      [Here is a ] ; link "sample" "doc/run.pli" options "filter_ascii" ; [.]

  header "Maintaining"

    para
      [The] ; fixed [ http://] ; italic [name_of_the_compter] ; fixed [/pliant/fullpliant/status.html ] ; [URL should provide you (remotely) most informations required to check the server status (memory, processor, disks, etc). ]
      [Some informations and actions are available only to a user with 'administration' rights.]

    para
      [You can use the Pliant file browser to (remotely) view/edit individual files.]

  header "Upgrading"

    [Uploading to well defined files will perform actions automatically:]
    table columns 3
      cell header [When uploading to]
      cell header [what does it mean]
      cell header [what does it do]
      cell fixed:[file:/boot/pliant.tgz]
      cell [you are installing a new Pliant release]
      cell
        [unpack at] ; fixed:[ file:/ ] ; [then recompile and restart Pliant services.]
      cell fixed:[file:/boot/fullpliant.tgz]
      cell [you are upgrading FullPliant server (including Linux kernel)]
      cell
        [unpack at] ; fixed:[ file:/] ; [, rerun Lilo, then reboot, recompile and restart Pliant services.]
      cell fixed:[file:/boot/debian.tgz]
      cell [you are upgrading the embedded computer]
      cell
        [unpack at] ; fixed:[ file:/debian/ ] ; [the next time the system boots.]


header "Implementation details"

  table columns 2
    cell (link "kernel.pli" "kernel.pli")
    cell
      [Installing the Linux kernel source tree, and compiling a custom kernel according the the target computer Pliant configuration database.]
    cell (link "debian.pli" "debian.pli")
    cell
      [Dealing with Debian packages (downloading, solving dependencies, unpacking)]
    cell (link "rules.pli" "rules.pli")
    cell
      [Computes all target computer individual settings according the the set of definitions.]
    cell (link "install.pli" "install.pli")
    cell
      [The main script for installing a FullPliant system.] 
  
  table columns 2
    cell (link "init.c" "init.c")
    cell [Will be called by Linux kernel at boot time when running a FullPliant distribution.]
    cell (link "boot.pli" "boot.pli")
    cell [Called once by FullPliant 'init' in order to configure the computer.]
    cell (link "run.pli" "run.pli")
    cell [Called by FullPliant 'init' in order to run Pliant services. When it stops, it's immediately restarted by 'init'.]
    cell (link "recover.pli" "run.pli")
    cell [Called by FullPliant recovery/install CD.]