summaryrefslogtreecommitdiffstats
path: root/build_tools/l7/larch0/docs/html/profiles.html
blob: a4c4a226ae771cbde25d6499cce12c5b7c8f299f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
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>