diff options
Diffstat (limited to 'build_tools/l7/larch0/docs/html/profiles.html')
| -rw-r--r-- | build_tools/l7/larch0/docs/html/profiles.html | 326 |
1 files changed, 326 insertions, 0 deletions
diff --git a/build_tools/l7/larch0/docs/html/profiles.html b/build_tools/l7/larch0/docs/html/profiles.html new file mode 100644 index 0000000..a4c4a22 --- /dev/null +++ b/build_tools/l7/larch0/docs/html/profiles.html @@ -0,0 +1,326 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> + +<html> +<head> +<meta http-equiv="Content-type" content="text/html; charset=utf-8" /> +<title>Profiles</title> +<!-- (en) Add your meta data here --> + +<link href="css/larchdocs.css" rel="stylesheet" type="text/css"/> +<!--[if lte IE 7]> +<link href="css/yaml/core/iehacks.css" rel="stylesheet" type="text/css" /> +<![endif]--> +</head> + +<body> +<!-- skip link navigation --> +<ul id="skiplinks"> + <li><a class="skip" href="#col1">Skip to main content (Press Enter).</a></li> +</ul> + +<div class="page_margins"> + <div class="page"> + <div id="top"><div id="tm"></div></div> + <!-- begin: #col1 --> + <div id="col1" role="main"> + <div id="col1_content"> + <div id="header" role="banner"> + <h1><span><em>live Arch Linux</em> builder</span></h1> + </div> + + <!-- begin: #col3 navigation column --> + <div id="col3" role="complementary"> + <div id="col3_content"> + <img class="indent2" alt="larch logo" src="css/screen/larch150x.png" width="150" height="150" /> + <div class="vlist"> + <ul> + <li><a href="index.html"><h6>Table Of Contents</h6></a></li> + <li><a href="larch_live_system.html"><h6>Next:</h6> + <div class="indent1">Structure of a larch live system</div></a></li> + <li><a href="medium.html"><h6>Previous:</h6> + <div class="indent1">Preparing the larch live medium</div></a></li> + </ul> + </div> + </div> + </div> + <!-- end: #col3 --> + +<div class="larchdocs"> +<h2 id="pagetitle" level="1">Profiles</h2> + +<p>This feature of the <em>larch</em> build system allows bundling +all the configuration information for a particular <em>live</em> system +'design' into a single directory, a <em>larch profile</em>, and the +name of the profile is the directory's name. This directory includes +the list of packages to be installed, locale information and the +particular tweaks and additions needed +to customize the system, in particular a subdirectory containing the +'overlay' files - those files which have been changed from their initial +fresh state after installation and those which have simply been added. +</p> + +<p>Note that of all the profile files and directories mentioned here +only 'addedpacks' is not optional. +</p> + +<h3><a name="overlay"></a>The overlay directory</h3> + +<p>One of the simplest features of the profile is perhaps the +'<em>rootoverlay</em>' subdirectory: +everything in this directory is copied directly to the +<em>live</em> system's overlay, so that the a file 'a/b/c' within this +directory will appear at '/a/b/c' in the <em>live</em> system, regardless +of whether this file previously existed. Note however that all ownerships +are changed to 'root:root'. The bulk of the customizations for the +<em>live</em> system would normally be placed in this directory. +</p> + +<p>It would be possible to make the desired alterations directly to the +base system, and there are situations in which one would pretty well +have to do it this way (for example if a modified or added file was to +have some ownership other than 'root:root'). But another advantage (apart +from the encapsulation of the customizations in the profile directory) of +keeping the modifications in a separate directory is that the base +installation can be kept 'clean' and thus it is easily reusable. +</p> + +<p>If you would like to have a look at a profile, look in the 'profiles' +directory in the 'larch-profiles' package (if you have downloaded +<em>larch</em> by means of the 'larch-setup' script that will be +'larch0/profiles'). Each of its subdirectories is a profile. +If you want to make your own profile, it is probably easiest to start with +one of the examples. Copy one of these directories to your working directory +and rename it (to avoid confusion). +</p> + +<h3><a name="cd-root"></a>The <strong>cd-root</strong> directory</h3> + +<p>This directory contains files that will be (more or less) directly copied +to the <em>larch</em> medium, partly dependent on the available bootloaders. +</p> + +<p>Bootloader independent files are provided in the 'larch' package at +'cd-root/boot0'. Individual files can be added or substituted by +supplying them in the <em>profile</em> at <strong>cd-root/boot</strong>. +It is also possible to completely replace the basic boot directory by +having <strong>cd-root/boot0</strong> in +the profile - then the default version will not be used. These files are +copied to the 'boot' directory of the bootable medium. +</p> + +<p>There are also directories for bootloader dependent files. These are only +copied over if the <em>live</em> system has support for the corresponding +bootloader (i.e. if the corresponding packages - 'grub' and 'syslinux' - are +installed). These end up as subdirectories of the medium's 'boot' directory, +'boot/grub', 'boot/syslinux' or 'boot/isolinux', and work in a similar way to +the 'boot(0)' directories. <em>larch</em> provides default versions of these +directories in 'cd-root/grub0' and 'cd-root/isolinux0'. To extend these, or +replace individual files, place your changes in the directories +<strong>cd-root/grub</strong> and <strong>cd-root/isolinux</strong> in the +<em>profile</em> directory, if +you want to completely replace these directories, supply your versions in +<strong>cd-root/grub0</strong> and <strong>cd-root/isolinux0</strong> in the +profile directory. +</p> + +<p>The contents of the directory <strong>cd-root/larch/copy</strong> will +appear in '/larch/copy' on the medium. During booting the <em>larch live</em> +system will copy the contents of this directory to the <em>tmpfs</em> base +directory ('/.livesys'). This feature is not +used by the <em>larch</em> system itself, but it can be used in various +ways by the <em>live</em> system - the example profiles use it to some +extent, for controlling autologin and for data required for installation +as a normal <em>Arch</em> system (information on features specific to a +<em>live</em> system which should be stripped out if a normal installation +is performed). +</p> + +<p>The contents of the directory <strong>cd-root/larch/extra</strong> will +appear in 'larch/extra' on the medium but are otherwise unconnected with any +<em>larch</em> functionality. <em>Live</em> system designers can use this +in any way they like. +</p> + +<h3><a name="other-files"></a>Other important files within a profile</h3> + +<ul> + <li><strong>addedpacks</strong> - This is the only compulsory file in + the profile (it must even be present if you are not using the + installation stage, but it can be empty in that case). It contains + a list of packages and package groups to be installed to the 'base' + system. Here you can enter all the applications + you would like in your <em>live</em> CD/USB system (and subsequently + installed to a hard disk partition, if that was your intention). + Thanks to <em>pacman</em> you don't need to sort out dependencies, + these should all be included automatically. See + <a href="archin.html#package_selection">here</a> for details. + </li> + <li><strong>vetopacks</strong> - Allows 'vetoing' of packages included + indirectly in the installation list from 'addedpacks'. See + <a href="archin.html#package_selection">here</a> for details. + </li> + <li><strong>pacman.conf.repos</strong> - Set the repository part of + 'pacman.conf' for the <em>live</em> system, and possibly also for + installation of the base system (See + <a href="archin.html#pacman_conf">here</a> for further details). + The default version will be adequate for many situations, but you + will need to supply this file if you use the 'testing' repository, + for example. + </li> + <li><strong>pacman.conf.options</strong> - Set the options part of + 'pacman.conf' for the <em>live</em> system and for + installation of the base system (See + <a href="archin.html#pacman_conf">here</a> for further details). + This will generally not be needed as the default version will be + adequate for most purposes. + </li> + <li><strong>bootlines</strong> - This file contains bootloader independent + boot lines, so that the same file can be used for grub and isolinux/syslinux. + The gui provides a button to edit this file. + To get an idea of what should be in here look at the default version (in + the 'larch' package, 'data' directory), or just click on the edit button. + </li> + + <li><strong>rootoverlay/etc/rc.conf</strong> - As a major point of + configuration in an <em>Arch</em> system this is important enough + to get a button in the <em>larch</em> gui to edit it. + </li> + + <li><strong>rootoverlay/etc/locale.gen</strong> - For convenience, the + <em>larch</em> gui provides a button to edit this file, which determines + which glibc locales are supported in the <em>live</em> system. The + corresponding files are generated (to the overlay) by the 'larchify' + script, which has an option (for experts only) to reuse the locale + files from a previous run (in order to reduce generation time in + cases where the locales are unchanged). + </li> + + <li><strong>rootoverlay/etc/mkinitcpio.conf.larch0</strong> - Again for + convenience, the <em>larch</em> gui provides a button to edit this file, + which allows you to tweak the initramfs. This is a special version of + '/etc/mkinitcpio.conf' which is used to generate the initramfs for the + <em>larch live</em> system. The default version is supplied as + '/etc/mkinitcpio.conf.larch0' in the 'larch-live' package. Whatever else + you change, don't change the larch hooks. + </li> + + <li><strong>rootoverlay/etc/inittab.larch</strong> - If this file is + present it will cause the original /etc/inittab to be saved with a + '.larchsave' suffix, and this new version will be used for the + <em>live</em> 'inittab'. This allows a special version of this file to + be used just for the <em>live</em> system, an installer + can replace it by the original during the installation process. + </li> + + <li><strong>users</strong> - It is possible to add user accounts to the + system during building. See below. + </li> + + <li><strong>skel_*</strong> (directory) - Customized '/etc/skel' substitutes + for use at build time only. See below. + </li> + + <li><strong>vetodirs</strong> - Do not use this unless you really know what + you are doing. Each directory listed in this file (one entry per line, + comment lines start with '#') will be excluded from the live system. The + directories are relative to the installation root. + </li> + + <li><strong>build-tweak</strong> - Do not use this unless you really know + what you are doing. It is a program (script) - so it must be executable - + to customize the construction of the overlay (to a certain extent). It gets + two arguments on the command line: the path to the installation being + larchified, and the (full) path to the directory in which the overlay is + being constructed. It is called just before 'mods.sqf' is squashed, but + also before users are added. + </li> + + <li><strong>nosave</strong> - The existence of this file will suppress the + generation of the file 'larch/save' on a writable medium (unless overridden + by an option to the medium generation script). It is also copied to + 'larch/nosave' on the medium (also on non-writable media), so that this + message is available later, e.g. when copying the medium. + </li> + +</ul> + +<h3><a name="users"></a>Adding user accounts</h3> + +<p> +The construction details should be provided in the 'users' file in the +profile directory. It is an 'ini'-style configuration file, the sections +being the user names. Here is an example: +<pre>[DEFAULT] +pw = +expert = +skel = +maingroup = +uid = +xgroups = video,audio,optical,storage,scanner,power,camera + +[u1] +uid = 999 +skel = + +[u2] +pw = p1 +expert = +skel = +maingroup = +uid = +xgroups = video,audio,optical,storage +</pre> +The 'DEFAULT' section is not necessary, but is generated automatically +by the gui user-table editor. Only entries which differ from the default +values need be present. +</p> +<p>The default primary group is defined by settings in '/etc/login.defs' +and '/etc/default/useradd' ('USERGROUPS_ENAB yes' in 'etc/login.defs' +causes this to be a group with the same name as the user). You can +override this by adding an 'expert' option, or by placing modified versions +of these files in the profile's 'rootoverlay' directory. +</p> +<p>The additional groups should be comma-separated and without spaces. +</p> +<p>If no 'skel'-file is specified, the default ('/etc/skel') is used, including +anything in the overlay. To use a custom 'skel'-file, place the directory +in the profile, giving it a name starting with 'skel_', and place the rest of +the name (the part after '_') in the configuration line. +</p> +<p>A password can be set for the new user by entering this (plain text - +I'm guessing this is alright in this situation ...). An empty password +field will allow passwordless logins (at least on the console). +</p> +<p>By default the UID number will be chosen automatically, but a specific +number may be entered here. In <em>Arch Linux</em> the UIDs normally start +at 1000. +</p> +<p>Users are added by means of 'useradd', so anything placed in the 'expert' +field should be a valid option to that command. If a user-name already exists +in the system to be larchified, it will be ignored (it does not count as +an error). +</p> + +</div> + + + <div class="topref"><a href="#top">Top</a></div> + </div> + <!-- begin: #footer --> + <div id="footer"> + <div id="footer-content" role="contentinfo">© 2010 Michael Towers<br /> + Page layout assisted by <a href="http://www.yaml.de/">YAML</a> and + <a href="http://www.kuwata-lab.com/tenjin/">pyTenjin</a> + </div> + </div> + <!-- end: #footer --> + </div> + <!-- end: #col1 --> + <div id="bottom"><div id="bl"><div id="bm"></div></div></div> + </div> +</div> +<!-- full skiplink functionality in webkit browsers --> +<script src="css/yaml/core/js/webkit-focusfix.js" type="text/javascript"></script> +</body> +</html> |