~fai/fai/fai.hardy : revision 2

1

<!DOCTYPE debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN" [

2

<!-- include version information so we don't have to hard code it

3

within the document -->

4

5

<!entity % commondata SYSTEM "common.ent" > %commondata;

6

7

<!entity svn-rev "$Id: fai-guide.sgml 4596 2007-09-17 11:26:32Z lange $">

8

9

<!entity faiver "3.2.1">

10

<!entity faiverdate "17 Sep 2007">

11

12

<!entity version "2.6.4">

13

<!entity date "17 September 2007">

14

15

<!entity faisetup system "entities/faisetup.sgml">

16

<!entity bootexample system "entities/bootexample.sgml">

17

<!entity bootlog system "entities/bootlog.sgml">

18

19

]>

20

21

22

23

<book>

24

<title>FAI Guide (Fully Automatic Installation)

25

26

<author>Thomas Lange <email>lange@informatik.uni-koeln.de</email>

27

<version>FAI Guide version &version;, &date; for FAI package version &faiver;

28

29

30

This manual describes the fully automatic installation package for

31

&dgl;. This includes the installation of the package, planning and

32

creating of the configuration and how to deal with errors.

33

34

35

36

37

38

</copyrightsummary>

39

40

This manual is free software; you may redistribute it and/or modify it

41

under the terms of the GNU General Public License as published by the

42

Free Software Foundation; either version 2, or (at your option) any

43

later version.

44

45

This is distributed in the hope that it will be useful, but

46

without any warranty; without even the implied warranty of

47

merchantability or fitness for a particular purpose. See the GNU

48

General Public License for more details.

49

50

A copy of the GNU General Public License is available as &file-GPL; in

51

the &dgl; distribution or on the World Wide Web at <url id="&url-gpl;"

52

name="the GNU website">. You can also obtain it by

53

writing to the &fsf-addr;.

54

55

56

57

<chapt id="intro">Introduction

58

<!--MT: general comments:

59

- dirinstall is only mentioned at the end

60

- mailinglists, IRC channel should be mentioned

61

- ULRs should be http://www. ... or only www. ..., but please be consistent

62

- Variables $VARNAME or VARNAME only? Be consistent.

63

-->

64

<sect id="availability">Availability

65

66

The homepage of FAI is <url id="&faiwww;">.

67

There you will find information about FAI, for example the mailing

68

list archives. The FAI package is also available as a Debian package from

69

<url id="&faidownload;">. It's an official Debian package and is available from

70

all Debian mirrors. To access the newest versions of the FAI packages,

71

you can add the following line to your <file>/etc/apt/sources.list</file> file.

72

73

<example>deb http://www.informatik.uni-koeln.de/fai/download etch koeln</example>

74

75

Send any bug or comment to

76

<email>fai@informatik.uni-koeln.de</email>. You can also use the

77

Debian bug tracking system (BTS)

78

<url id="http://&www-debian-org;/Bugs/"> for reporting errors.

79

80

81

You can access the subversion repository containing the newest developer

82

version of FAI from a Unix shell using the

83

following commands.

84

85

# svn co svn://svn.debian.org/svn/fai/trunk fai

86

</example>

87

88

You can also use the web interface for the subversion repository at:

89

<httpsite>svn.debian.org/</httpsite><httppath>wsvn/fai/</httppath>.

90

91

Now read this manual, then enjoy the fully automatic installation and

92

your saved time.

93

94

95

<sect id="motivation">Motivation Have you ever performed identical

96

installations of an operating system several times? Would you like to

97

be able to install a Linux cluster with dozens of nodes single

98

handedly?

99

100

101

Repeating the same task again and again is boring -- and will surely

102

lead to errors. Also a whole lot of time could be saved if the

103

installations were done automatically. An installation process with

104

manual interaction does not scale. But clusters have the habit of

105

growing over the years. Think long-term rather than planning just a

106

few months into the future.

107

108

109

In 1999, I had to perform an installation of a Linux cluster with one

110

server and 16 clients. Since I had much experience doing automatic

111

installations of Solaris operating systems on SUN SPARC hardware, the

112

idea to build an automatic installation for Debian was born. Solaris

113

has an automatic installation feature called JumpStart<footnote>

114

Solaris 8 Advanced Installation Guide at

115

<httpsite>docs.sun.com</httpsite> </footnote>. In conjunction

116

with the auto-install scripts from Casper Dik<footnote><url

117

id="ftp://ftp.wins.uva.nl:/pub/solaris/auto-install/"> </footnote>,

118

I could save a lot of time not only for every new SUN computer, but

119

also for re-installation of existing workstations. For example, I had

120

to build a temporary LAN with four SUN workstations for a conference,

121

which lasted only a few days. I took these workstations out of our normal

122

research network and set up a new installation for the conference.

123

When it was over, I simply integrated the workstations back into the

124

research network, rebooted just once, and after half an hour,

125

everything was up and running as before. The configuration of all

126

workstations was exactly the same as before the conference, because

127

everything was performed by the same installation process. I also used

128

the automatic installation for reinstalling a workstation after a

129

damaged hard disk had been replaced. It took two weeks until I

130

received the new hard disk but only a few minutes after the new disk

131

was installed, the workstation was running as before. And this is why

132

I chose to adapt this technique to a PC cluster running Linux.

133

134

135

136

<sect id="overview">Overview and concepts

137

138

FAI is a non-interactive system to install a &dgl; operating system

139

on

140

a single computer or a whole cluster. You can take one or more virgin

141

PCs, turn on the power and after a few minutes Linux is installed,

142

configured and running on the whole cluster, without any interaction

143

necessary. Thus, it's a scalable method for installing and updating a

144

cluster unattended with little effort involved. FAI uses the &dgl;

145

distribution and a collection of shell and Perl scripts for the

146

installation process. Changes to the configuration files of the

147

operating system can be made by cfengine, shell, Perl and expect scripts.

148

149

150

FAI's target group are system administrators who have to install

151

Debian onto one or even hundreds of computers. Because it's a general

152

purpose installation tool, it can be used for installing a Beowulf

153

cluster, a rendering farm or a Linux laboratory or a classroom. Also

154

large-scale Linux networks with different hardware or different installation

155

requirements are easy to establish using FAI. But don't forget to plan

156

your installation. <ref id="plan"> has some useful hints for this topic.

157

158

First, some terms used in this manual are described.

159

160

161

<tag> install server : <item> The host where the package

162

<tt>fai-server</tt> is installed. It provides several services and data for

163

all install clients. In the examples of this manual this

164

host is called <tt>faiserver</tt>.

165

166

<tag>install client : <item> A host which will be installed using

167

FAI and a configuration provided by the install server. Also called

168

client for short. In this manual, the example hosts are

169

called <tt>demohost, nucleus, atom01, atom02,...</tt> </item>

170

<tag> configuration : <item> The details of how the installation

171

of the clients should be performed. This includes information about:

172

<list>

173

<item> Hard disk layout </item>

174

<item> Local file systems, their types, mount points

175

and mount options </item>

176

<item> Software packages </item>

177

<item> Keyboard layout, time zone, NIS,

178

Xorg configuration, remote file systems, user accounts,

179

printers ... </item>

180

</list>

181

<tag> nfsroot : <item> A file system located on the install

182

server. It's the complete file system for the install

183

clients during the installation process. All clients share the

184

same nfsroot, which they mount read only.</item>

185

</taglist>

186

187

<sect id="work">How does FAI work?

188

189

The install client which will be installed using FAI, is

190

booted from floppy disk or via network card. It gets an IP address and

191

boots a Linux kernel which mounts its root file system via NFS from the install

192

server. After the kernel is loaded, the FAI startup script

193

performs the automatic installation which doesn't need any

194

interaction. First, the hard disks will be partitioned, file systems are

195

created and then software packages are installed. After that, the new

196

installed operating system is configured to your local needs using

197

some scripts. Finally the new operating system will be booted from the local

198

disk.

199

200

The details of how to install the computer (the configuration) are

201

stored in the configuration space on the install server. Configuration

202

files are shared among groups of computers if they are similar using the

203

class concept. So you need not create a configuration for every new

204

host. Hence, FAI is a scalable method to install a big cluster with a

205

great number of nodes.

206

207

208

FAI can also be used as a network rescue system. You can boot your

209

computer, but it will not perform an installation. Instead it will run a

210

fully functional &dgl; without using the local hard disks. Then you can

211

do a remote login and backup or restore a disk partition, check a file system,

212

inspect the hardware or do any other task.

213

214

<!--MT: here the class concept should be described, move the entire section

215

here.-->

216

217

<sect id="features">Features

218

219

<list>

220

<item> A fully automated installation can be performed. </item>

221

<item> Very quick unattended installation </item>

222

<item> Update of running systems without re-installation </item>

223

<item> Hosts can boot from network card, CD, USB stick or floppy. </item>

224

<item> Easy creation of the CD, USB stick or floppy boot media </item>

225

<item> PXE with DHCP and BOOTP boot methods are supported. </item>

226

<item> Lilo and grub support </item>

227

<item> ReiserFS, ext3 and XFS file system support </item>

228

<item> Automatic hardware detection </item>

229

<item> Remote login via ssh during installation process

230

possible. </item>

231

<item> Two additional virtual terminals available

232

during installation </item>

233

<item> All similar configurations are shared among

234

all install clients. </item>

235

<item> Log files for all installations are saved to the installation server. </item>

236

<item> Shell, Perl, expect and cfengine scripts are

237

supported for the configuration setup. </item>

238

<item> Access to a Debian mirror via NFS, FTP or HTTP </item>

239

<item> Keyboard layout selectable </item>

240

<item> Can be used as a rescue system. </item>

241

<item> Tested on SUN SPARC hardware running Linux or Solaris. </item>

242

<item> Flexible system through easy class concept </item>

243

<item> Predefined Beowulf classes included </item>

244

<item> Diskless client support </item>

245

<item> Easily add your own functions via hooks. </item>

246

<item> Easily change the default behavior via hooks. </item>

247

248

</list>

249

250

<chapt id=impatient>Quickstart - For the impatient user

251

252

So, you do not like to read the whole manual? You like to try an

253

installation without reading the manual? OK. Here's how to succeed in

254

a few minutes.

255

256

<list>

257

<item>Install the package <tt>fai-server</tt> and all recommended packages (see

258

<ref id="faisetup"> on your install server).</item>

259

<item>Edit &fc;, run fai-setup -v and read its output.</item>

260

261

<item>

262

Install the simple examples into the configuration space:

263

<tt>cp -a /usr/share/doc/fai-doc/examples/simple/* /srv/fai/config/</tt>

264

</item>

265

266

<item>Get the MAC address of your demo host.</item>

267

<item>Add your host (try to name it <tt>demohost</tt>)

268

to <file>dhcpd.conf</file> and <file>/etc/hosts</file> (=your DNS) on the FAI server.</item>

269

<item>When using PXE, tell the install client to boot the install

270

kernel and perform an installation during the next boot <example>fai-chboot -IFv demohost</example>

271

</item>

272

<item>If you want to try FAI without setting up a PXE+DNS+DHCP-environment:

273

put the host names into <file>/etc/hosts</file> inside the nfsroot at

274

<file>/srv/fai/nfsroot</file> and use

275

a bootfloppy/CD/DVD to boot the client.

276

See <manref name="make-fai-bootfloppy" section="8">.

277

<item>Boot your demo host and enjoy the fully automatic installation.</item>

278

<item>If the installation has finished successfully, the computer should boot a

279

small Debian system. You can login as user <tt>demo</tt> or <tt>root</tt> with password <tt>fai</tt>.</item>

280

281

</list>

282

But now don't forget to read chapters <ref id="plan">, <ref id="instprocess"> and <ref id="config">!

283

284

<chapt id="inst">Installing FAI

285

<sect id="requirements">Requirements

286

<!--MT: split this section to mark the specific requirments:

287

- boot media

288

- source of the root file system

289

- config source

290

-->

291

292

The following items are required for an installation via FAI.

293

294

295

<tag>A computer: </tag><item> The computer must have a

296

network interface card<footnote>If you install from USB

297

stick or CD you do not need a network

298

card</footnote>. Unless a diskless installation

299

should be performed a local hard disk is also needed. No floppy disk,

300

CD-ROM, keyboard or graphics adapter is needed.</item>

301

302

<tag>DHCP or BOOTP server: </tag><item>

303

The clients need one of these daemons to obtain boot information. But

304

you can also put all this information onto the boot floppy.</item>

305

306

<tag>TFTP server:<item> The TFTP daemon is used for

307

transferring the kernel to the clients. It's only needed when

308

booting from network card with a boot PROM.</item>

309

<tag>NFS-Root:<item> It is a mountable directory which contains the whole

310

file system for the install clients during installation. It will

311

be created during the setup of the FAI package and is also

312

called nfsroot.</item>

313

<tag>Debian mirror:<item> Access to a Debian

314

mirror is needed. A local mirror of all Debian packages or

315

an <manref name="apt-proxy" section="8"> is recommended if

316

you install several computers.</item>

317

<tag>Install kernel: <item> The kernel image and the initial

318

RAM disk that is used

319

for booting the install clients. It mounts its root file system via NFS. </item>

320

<tag>Configuration space:<item> This directory tree, which

321

contains the configuration data, is mounted via NFS by

322

default. But you can also get this directory from a revision

323

control system like CVS or subversion.

324

</taglist>

325

326

The TFTP daemon and an NFS server will be enabled automatically when

327

installing the <tt>fai-server</tt> package.

328

329

330

331

<sect id="debian-mirror">How to create a local Debian mirror

332

333

334

The script <prgn>mkdebmirror</prgn> <footnote> You can find the script in

335

<file>/usr/share/doc/fai-doc/examples/utils/</file>. </footnote> can be used

336

for creating your own local Debian mirror. This script uses the

337

script <manref name="debmirror" section="1"> and <manref name="rsync"

338

section="1">. A partial Debian mirror only for i386 architecture for

339

Debian 4.0 (aka etch) without the source packages needs about

340

&mirrorsize of disk space. Accessing the mirror via HTTP will be the

341

normal way in most cases. To see more output from the

342

script call <tt>mkdebmirror --debug</tt>. A root account is not

343

necessary to create and maintain the Debian mirror.

344

345

You can use the command <manref name="fai-mirror" section="1"> for

346

creating a partial mirror that only contains the software

347

packages that are used in the classes in your configuration

348

space. A partial mirror containing all package for the simple

349

examples from the package fai-doc will only need about 300MB of disk

350

space.

351

352

To use HTTP access to the local Debian mirror, install a web server

353

and create a symlink to the local directory where your mirror

354

is located:

355

356

<example># apt-get install apache2

357

# ln -s /files/scratch/debmirror /var/www/debmirror

358

</example>

359

360

Create a file <manref name="sources.list" section="5"> in

361

<file>/etc/fai/apt</file> which gives access to your Debian mirror. An

362

example can be found in

363

<file>/usr/share/doc/fai-doc/examples/etc</file>. Also add the IP-address

364

of the HTTP server to the variable <var>NFSROOT_ETC_HOSTS</var> in

365

&mfnc; when the install clients have no DNS access.

366

367

368

<sect id=faisetup> Setting up FAI

369

370

To setup a FAI install server you need at least the packages

371

<tt>fai-server</tt> and <tt>fai-doc</tt>. The package

372

<tt>fai-quickstart</tt> contains dependencies on all required packages

373

for an install server. Do not install the package <tt>fai-nfsroot</tt>

374

on a normal system. This package can only be installed inside the nfsroot.

375

376

If you would like to install all packages that are useful

377

for a FAI install server, use the following command

378

379

380

# aptitude install fai-quickstart

381

Reading Package Lists... Done

382

Building Dependency Tree

383

Reading extended state information

384

Initializing package states... Done

385

Reading task descriptions... Done

386

The following NEW packages will be automatically installed:

387

dhcp3-common dhcp3-server fai-client fai-doc fai-server

388

tftp-hpa tftpd-hpa

389

The following NEW packages will be installed:

390

dhcp3-common dhcp3-server fai-client fai-doc fai-quickstart

391

fai-server tftp-hpa tftpd-hpa

392

0 packages upgraded, 9 newly installed, 0 to remove and 0 not upgraded.

393

Need to get 13.0MB of archives. After unpacking 17.9MB will be used.

394

Do you want to continue? [Y/n/?]

395

</example>

396

397

The suggested packages for FAI are: <tt>debmirror, mknbi, apt-move, mkisofs, grub, aptitude</tt>.

398

399

400

The configuration for the FAI package (not the configuration data

401

for the install clients) is defined in &fc;. Definitions that are only

402

used for creating the nfsroot are located in &mfnc;. Edit these files before calling

403

<prgn>fai-setup</prgn>. These are important variables in &mfnc;:

404

405

406

<tag><var>FAI_DEBOOTSTRAP</var></tag>

407

<item>

408

For building the nfsroot there's the command called

409

<manref name="debootstrap" section="8">. It needs

410

the location of a Debian mirror and the name of the distribution

411

(etch, lenny, sid) for which the basic Debian

412

system should be built.

413

</item>

414

415

<tag><var>NFSROOT_ETC_HOSTS</var></tag>

416

<item>

417

If you use HTTP or FTP access to the Debain mirror,

418

add its IP-address and the name to this

419

variable. For a Beowulf master node, add the name and

420

IP-address of both networks to it. This variable is not

421

needed when the clients have access to a DNS server.

422

</item>

423

424

<!--MT: don't keep obsolete information

425

<tag><var>FAI_SOURCES_LIST</var></tag> <item> Now

426

OBSOLETE and unsupported. Use the file

427

<file>/etc/fai/apt/sources.list</file> instead.

428

</item>

429

430

<tag><var>KERNELPACKAGE</var></tag>

431

<item>

432

THE USE OF THIS VARIABLE IS NOW OBSOLETE.</item>

433

<tag> <var>NFSROOT_PACKAGES</var></tag>

434

<item>

435

THE USE OF THIS VARIABLE IS NOW OBSOLETE. Use

436

<file>/etc/fai/NFSROOT</file> instead.</item>

437

-->

438

439

440

<item>

441

which of DHCP and/or BOOTP the server should create setups for

442

(when make-fai-nfsroot is run). If undefined (the default)

443

it means to create the setup for both protocols.

444

</item>

445

<tag><var>NFSROOT_HOOKS</var></tag>

446

<item>

447

A directory containing shell scripts, which are sourced at

448

the end of make-fai-nfsroot for additional modifications

449

of the NFSROOT.

450

Defaults to /etc/fai/nfsroot-hooks.

451

</item>

452

</taglist>

453

454

455

456

These are important variables in &fc;:

457

458

<!--MT: don't keep obsolete information

459

<tag><var>FAI_LOCATION</var></tag>

460

<item> THE USE OF THIS VARIABLE IS NOW OBSOLETE. Use

461

the variable <var>FAI_CONFIG_SRC</var> instead.</item>

462

-->

463

464

<tag><var>FAI_CONFIG_SRC</var></tag>

465

<item> This variables described how to access the

466

configuration space on the install clients. It's an Universal Resource

467

Identifier (URI) even it may not always comply to the

468

official schemes. <!--MT: not so important... See

469

<httpsite>en.wikipedia.org</httpsite><httppath>/wiki/URI_scheme</httppath>

470

for details.-->

471

Currently supported methods are:

472

473

474

<tag><var>nfs://host/path/to/exported/config</var></tag>

475

<item> The config space is mounted from host via NFS.</item>

476

477

<tag><var>cvs[+ssh]://user@host/path/to/cvsroot

478

module[=tag]</var></tag>

479

<item> The config space is received from a cvs checkout.</item>

480

481

<tag><var>svn://user@host/svnpath</var></tag>

482

<item> The config space checked out from a

483

subversion repository. Also supported are svn+file,

484

svn+http, svn+ssh, svn+https and checkouts without a user

485

name.</item>

486

487

488

<item> The config space checked out from a

489

git repository, host can be empty. Also supported is git+http.</item>

490

</taglist>

491

492

If <var>FAI_CONFIG_SRC</var> is undefined in &fc, then the

493

default is to use an NFS mount from the fai install server

494

onto the install client. It's the same as

495

<tt>nfs://`hostname`/$FAI_CONFIGDIR</tt> with the host name

496

determined on the install server. Remember that this directory

497

must be exported to all install clients, so that all files

498

can be read by root. </item>

499

500

501

<tag><var>FAI_DEBMIRROR</var></tag>

502

<item>

503

If you have NFS access to your local Debian mirror,

504

specify the remote file system. It will be mounted to

505

<var>$MNTPOINT</var>, which must also be defined. It's

506

not needed if you use access via FTP or HTTP.

507

</item>

508

</taglist>

509

510

511

The content of <file>/etc/fai/apt/sources.list</file> and <var>FAI_DEBMIRROR</var>

512

are used by the install server and also by the clients. If your

513

install server has multiple network cards and different host names for

514

each card (as for a Beowulf server), use the install

515

server name which is known by the install clients.

516

517

518

FAI uses <manref name="apt-get" section="8"> to create the nfsroot

519

file system in <file>/srv/fai/nfsroot</file>. It needs about

520

&nfsrootsize; of free disk space. After editing &fc; and &mfnc; call

521

<prgn>fai-setup</prgn>.

522

523

524

&faisetup;

525

526

527

A complete log of fai-setup is available on the FAI web page.

528

It's important that you find both lines that are marked with an

529

asterisk in your output. Otherwise something went wrong. If you'll get a lot of blank

530

lines, it's likely that you are using <tt>konsole</tt>, the X terminal

531

emulation for KDE which has a bug. Try again using <tt>xterm</tt>.

532

533

534

The warning messages from dpkg about dependency problems can be ignored.

535

If you have problems running fai-setup, they usually stem from

536

<manref name="make-fai-nfsroot" section="8">. You may restart it by

537

calling 'make-fai-nfsroot -r'

538

(recover). Adding '-v' gives you a more verbose output which may help you

539

pinpoint the error. If you want to create a log file you may use

540

<tt>

541

sudo make-fai-nfsroot -r -v 2>&1 | tee make-fai-nfsroot.log

542

</tt>

543

It may help to enter the chroot environment manually

544

545

sudo chroot /srv/fai/nfsroot/live/filesystem.dir

546

</example>

547

The setup routine adds some lines to <file>/etc/exports</file> to export

548

the nfsroot and the configuration space to all hosts that belong to

549

the netgroup faiclients. If you already export a parent directory

550

of these directories, you may comment out these lines, since the kernel NFS

551

server has problems exporting a directory and one of its

552

subdirectories with different options.

553

554

All install clients must belong to this netgroup,

555

in order to mount these directories successfully. Netgroups are

556

defined in <file>/etc/netgroup</file> or in the corresponding NIS

557

map. An example for the netgroup file can be found in

558

<file>/usr/share/doc/fai-doc/examples/etc/netgroup</file>. For more

559

information, read the manual pages <manref name="netgroup"

560

section="5"> and the NIS HOWTO. After changing the netgroups, the NFS

561

server has to reload its configuration. Use one of the following

562

commands, depending on which NFS server you are using:

563

564

565

faiserver# /etc/init.d/nfs-kernel-server reload

566

faiserver# /etc/init.d/nfs-user-server reload

567

</example>

568

569

570

571

The setup also creates the account <tt>fai</tt> (defined by <var>$LOGUSER</var>)

572

if not already available. So you can add a user before calling <manref

573

name="fai-setup" section="8"> using the command

574

<manref name="adduser" section="8"> and use this as your local account

575

for saving log files. The log

576

files of all install clients are saved to the home directory of this

577

account. If you boot from network card, you should change the primary

578

group of this account, so this account has write permissions to

579

<file>/srv/tftp/fai</file> in order to change the symbolic links to the kernel

580

image which is booted by a client.

581

582

583

584

585

After that, FAI is installed successfully on your server, but has no

586

configuration for the install clients. Start with the examples from

587

<tt> /usr/share/doc/fai-doc/examples/simple/</tt> using the copy command above

588

and read <ref id="config">. Before you can set up a DHCP or BOOTP

589

daemon, you should collect some network information of all your

590

install clients. This is described in section <ref id="bootfloppy">.

591

592

When you make changes to &fc;, &mfnc; the nfsroot has to be rebuilt by calling <manref

593

name="make-fai-nfsroot" section="8">. If you only like to install a new kernel to

594

the nfsroot add the flags <tt>-k</tt> or <tt>-K</tt> to

595

<tt>make-fai-nfsroot</tt>. This will not recreate your nfsroot, but

596

only updates your kernel and kernel modules inside the nfsroot or add

597

additional packages into the nfsroot.

598

599

<sect1 id=troublefaisetup> Troubleshooting the setup

600

601

The setup of FAI adds the <tt>fai</tt> account, exports file systems and calls

602

<manref name="make-fai-nfsroot" section="8">. If you call

603

<tt>make-fai-nfsroot -v</tt> you

604

will see more messages. When using a local Debian mirror, it's

605

important that the install server can mount this directory via

606

NFS. If this mount fails, check <file>/etc/exports</file> and <file>/etc/netgroup</file>.

607

608

609

<chapt id="booting">Preparing booting

610

611

Before booting the client for the first time, you have to choose which medium you

612

use for booting. You can use the boot floppy or configure the computer

613

to boot via network card using a boot PROM.

614

Also booting from CD-ROM or from an USB stick is easy to set up. The

615

preferred method for booting is using PXE. PXE is the Preboot Execution

616

Environment which most modern network cards support.

617

618

619

<sect id="nicboot">Enabling PXE on a 3Com network card with boot PROM

620

621

If you have a 3Com network card that is equipped with a boot ROM by

622

Lanworks Technologies or already includes the DynamicAccess Managed PC

623

Boot Agent (MBA) software<footnote> <httpsite>support.3com.com/</httpsite>

624

<httppath>infodeli/tools/nic/mba.htm</httppath></footnote>, you

625

can enter the MBA setup by typing <tt>Ctrl+Alt+B</tt> during boot. The

626

setup should look like this:

627

628

629

630

Managed PC Boot Agent (MBA) v4.00

631

632

633

===============================================================================

634

Configuration

635

636

Boot Method: PXE

637

638

Default Boot: Network

639

Local Boot: Enabled

640

Config Message: Enabled

641

Message Timeout: 3 Seconds

642

Boot Failure Prompt: Wait for timeout

643

===============================================================================

644

Use cursor keys to edit: Up/Down change field, Left/Right change value

645

ESC to quit, F9 restore previous settings, F10 to save

646

</example>

647

648

Set the boot method to <tt>PXE</tt> (do not use RPL or BOOTP) and

649

enable local boot in this

650

menu. So the first boot device will be the network card using PXE, and

651

the second should be the local hard disk. This has to be configured in

652

the BIOS of your computer. For using the BOOTP protocol

653

choose <tt>TCP/IP</tt> and set the protocol to <tt>BOOTP</tt>.

654

655

When using BOOTP, you have to make a

656

symbolic link from the host name of your client to the appropriate

657

kernel image in <file>/srv/tftp/fai</file>. You can also use the utility

658

<prgn>tlink</prgn> (<file>/usr/share/doc/fai-doc/examples/utils/tlink</file>) to create

659

this link. The file

660

<file>installimage_3com</file> is created by <prgn>imggen</prgn> and

661

is suitable for booting 3Com network cards.<footnote> If you have

662

problems booting with a 3Com network card and get the error "BOOTP

663

record too large" after the kernel is transfered to the computer, try

664

the imggen-1.00 program to convert the netboot image to a

665

installimage_3com image. I had this problem using netboot 0.8.1-4 and

666

Image Creator for MBA ROMs v1.01, Date: Nov 26, 2001 but only on an

667

Athlon computer.

668

</footnote>

669

670

671

<sect id="pxeboot">Booting from network card with a PXE conforming boot ROM

672

Most modern bootable network cards support the PXE boot environment.

673

Some network cards (e.g. on notebooks) have a fixed

674

boot configuration, so they can only use the PXE boot protocol. This requires a PXE

675

Linux boot loader and a special version of the <tt>TFTP</tt> daemon,

676

which is available in the Debian package <package>tftpd-hpa</package>.

677

678

First install following additional needed packages:

679

680

681

# apt-get install dhcp3-server syslinux tftpd-hpa

682

</example>

683

684

Then set up the DHCP daemon. A sample configuration file can be

685

found in <file>/usr/share/doc/fai-doc/examples/etc/dhcpd.conf</file>. Copy

686

this file to <file>/etc/dhcp3/dhcpd.conf</file>.

687

Then enable the special tftp daemon

688

using this line in file <file>/etc/inetd.conf</file>:

689

690

tftp dgram udp wait root /usr/sbin/in.tftpd in.tftpd -s /srv/tftp/fai

691

</example>

692

693

The install client then loads the pxelinux boot loader which receives

694

its configuration via TFTP from a file in the directory

695

<file>/srv/tftp/fai/pxelinux.cfg</file> (defined by the variable

696

<var>TFTPROOT</var> in &mfnc;). Using the command <manref

697

name="fai-chboot" section="8"> you can

698

define which kernel will be loaded by the PXE Linux loader and

699

which additional parameters are passed to this kernel. You should

700

read the manual pages, which give you some good examples.

701

<!--MT: $TFTPROOT only tells FAI where the tftpd directory is found, but what

702

you are saying here rather refers to the entry in inetd.conf-->

703

704

See <file>/usr/share/doc/syslinux/pxelinux.doc</file> for more

705

information about how to boot such an environment. The PXE

706

environment uses the original kernel image (not the netboot image made

707

by mknbi-linux) which is copied to

708

<file>/srv/tftp/fai/vmlinuz-install</file>.

709

710

711

712

<sect id="bootfloppy">Creating a boot floppy

713

714

715

If your network card can't boot by itself, you have two options. The

716

first is to create a small boot floppy that uses etherboot, which

717

will provide the PXE feature for your network card. So you can

718

use DHCP and TFTP to get the install kernel that was created with

719

<manref name="mknbi-linux" section="8">. A lot of ethernet cards

720

support booting via ethernet if a special boot EPROM is inserted or

721

booted from floppy provided by <httpsite>rom-o-matic.net/</httpsite>. In

722

depth documentation about booting via ethernet may be found at

723

<httpsite>www.etherboot.org</httpsite>.

724

725

726

The second option is to boot via floppy disk that is created with the

727

command <manref name="make-fai-bootfloppy" section="8">. Since there's

728

no client specific

729

information on this floppy, it's suitable for all your install

730

clients. You can also specify additional kernel parameters for this

731

boot floppy or set other variables, if desired. Do not enable BOOTP

732

support when you have a DHCP server running in your network and vice

733

versa. This could lead to missing information. There's also a manual

734

page for <manref name="make-fai-bootfloppy" section="8">. If you have

735

no BOOTP or DHCP server, supply the network configuration as kernel

736

parameters. The format is

737

738

739

</tt>

740

for setting up the network and

741

<tt>nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>]</tt>

742

for specifying the nfsroot (which is required as the default path is not

743

suitable for FAI.)

744

745

For additional information see

746

<file>/usr/src/linux/Documentation/nfsroot.txt</file> in the kernel

747

sources.

748

749

<sect id="cdboot">Booting from a CD-ROM

750

751

It's possible to perform an automatic installation from CD-ROM without

752

an install server. The CD-ROM contains all data needed for the

753

installation. The command <manref name="fai-cd" section="8"> puts the

754

nfsroot, the configuration space and a subset of the Debian mirror

755

onto a CD-ROM. The partial mirror is created using the command

756

<manref name="fai-mirror" section="1"> which contains all packages

757

that are used by the classes used in your configuration space.

758

759

A sample ISO image is available at

760

<httpsite>www.informatik.uni-koeln.de</httpsite><httppath>/fai/fai-cd/</httppath>.

761

762

<sect id="usbboot">Booting from USB stick

763

764

Using the command <manref name="fai-cd" section="8"> you can also

765

create a bootable USB stick. First format your stick with an ext2 file

766

system (ext3 makes no sense on flash memory devies). Then mount it.

767

After that call:

768

<tt>fai-cd -m /path/to/mirror -u /path/to/mounted/stick</tt>

769

Then unmount the USB stick.

770

771

The USB stick must be formatted with an ext2 file system. VFAT is not

772

yet tested. Currently the file system that will be written onto the

773

stick is not compressed.

774

775

<sect id="mac">Collecting Ethernet addresses

776

777

Now it's time to boot your install clients for the first time. They

778

will fail to boot completely, because no BOOTP or DHCP daemon is running yet or

779

recognizes the hosts. But you can use this first boot attempt to

780

easily collect all Ethernet addresses of the network cards.

781

782

783

You have to collect all Ethernet (MAC) addresses of the install clients

784

and assign a host name and IP address to each client. To collect

785

all MAC addresses, now boot all your install clients. While the

786

install clients are booting, they send broadcast packets to the LAN. You

787

can log the MAC addresses of these hosts by running the following

788

command simultaneously on the server:

789

790

<example># tcpdump -qtel broadcast and port bootpc >/tmp/mac.list</example>

791

792

793

After the hosts have been sent some broadcast packets (they will fail

794

to boot because <prgn>bootpd</prgn> isn't running or does not recognize the MAC

795

address yet) abort <prgn>tcpdump</prgn> by typing <tt>ctrl-c</tt>. You get a list

796

of all unique MAC addresses with these commands:

797

798

<example># perl -ane 'print "\U$F[0]\n"' /tmp/mac.lis|sort|uniq</example>

799

800

After that, you only have to assign these MAC addresses to host names

801

and IP addresses (<file>/etc/ethers</file> and <file>/etc/hosts</file>

802

or corresponding NIS maps). With this information you can configure

803

your <prgn>BOOTP</prgn> or <prgn>DHCP</prgn> daemon (see the section

804

<ref id="bootptab">). I recommend to write the MAC addresses (last

805

three bytes will suffice if you have network cards from the same

806

vendor) and the host name in the front of each chassis.

807

808

<sect id=bootptab>Configuration of the BOOTP daemon

809

810

You should only use this method if you can't use a DHCP server, since

811

it's easier to create and manage the configuration for DHCP.

812

An example configuration for the BOOTP daemon can be found in

813

<file>/usr/share/doc/fai-doc/examples/etc/bootptab</file>.

814

815

816

# /etc/bootptab example for FAI

817

# replace FAISERVER with the name of your install server

818

819

.faiglobal:\

820

:ms=1024:\

821

:hd=/srv/tftp/fai:\

822

:hn:bs=auto:\

823

:rp=/srv/fai/nfsroot:

824

825

.failocal:\

826

:tc=.faiglobal:\

827

:sa=FAISERVER:\

828

:ts=FAISERVER:\

829

:sm=255.255.255.0:\

830

:gw=134.95.9.254:\

831

:dn=informatik.uni-koeln.de:\

832

:ds=134.95.9.136,134.95.100.209,134.95.100.208,134.95.140.208:\

833

:nt=time.rrz.uni-koeln.de,time2.rrz.uni-koeln.de:

834

835

# now one entry for each install client

836

demohost:ha=0x00105A240012:bf=demohost:tc=.failocal:T172="verbose sshd createvt debug":

837

ant01:ha=0x00105A000000:bf=ant01:tc=.failocal:T172="sshd":

838

</example>

839

840

841

Insert one entry for each install client at the end of this file as

842

done for the hosts demohost and ant01. Replace the string

843

<tt>FAISERVER</tt> with the name of your install server. If the

844

install server has multiple network cards and host names, use the host

845

name of the network card to which the install clients are

846

connected. Then adjust the other network tags (<tt>sm, gw, dn,

847

ds</tt>) to your local needs.

848

849

850

<tag>sm:</tag> <item> Subnet mask </item>

851

<tag>gw:</tag> <item> Default gateway / router </item>

852

<tag>dn:</tag> <item> Domain name </item>

853

<tag>ds:</tag> <item> List of DNS server. The

854

<file>/etc/resolv.conf</file> file will be created using this list

855

of DNS servers and the domain name.

856

<tag>T172:</tag> <item> List of <var>FAI_FLAGS</var>;

857

e.g. verbose, debug, reboot, createvt, sshd </item>

858

</taglist>

859

860

The tag for time servers (<tt>nt</tt>) are

861

optional. Tags with prefix <tt>T</tt> (starting from T170) are generic

862

tags which are used to transfer some FAI specific data to the

863

clients<footnote>T170=FAI_LOCATION (now defined in

864

<file>fai.conf</file>) and T171=FAI_ACTION. You can define theses

865

variables in a class/*.var script. But for backward compatibility, you

866

can define theses variables also from a BOOTP or DHCP

867

server.</footnote>

868

869

The list of <var>FAI_FLAGS</var> can be space or comma

870

separated. <var>FAI_FLAGS</var> in <file>bootptab</file> must be

871

separated by whitespace. If you define <var>FAI_FLAGS</var> as

872

an additional kernel parameter, the flags must be separated with a

873

comma.

874

If you do not have full control over the BOOTP or DHCP daemon (because

875

this service is managed by a central service group) you can also

876

define the variable <var>FAI_ACTION</var> in

877

the <file>/fai/class/*.var</file> scripts.

878

879

When you have created your <file>bootptab</file> file, you have to

880

enable the BOOTP daemon once. It's installed but Debian does not enable it

881

by default. Edit <file>/etc/inetd.conf</file> and remove the comment

882

(the hash) in the line containing <tt>#bootps</tt>. Then tell

883

<prgn>inetd</prgn> to reload its configuration.

884

885

<example># /etc/init.d/inetd reload</example>

886

887

The BOOTP daemon automatically reloads the configuration file if any changes are

888

made to it. The daemon for DHCP must always be manually restarted

889

after changes to the configuration file are made.

890

891

892

Now it's time to boot all install clients again!

893

FAI can perform several actions when the client is booting. This action

894

is defined in the variable <var>FAI_ACTION</var>.

895

Be very careful if you set <var>FAI_ACTION </var> to

896

install. This can destroy all your data on the install

897

client, indeed most time it should do this ;-). It's recommended to change this only

898

on a per-client base in the BOOTP configuration. Do not change it in

899

the section <tt>.failocal</tt> in <file>/etc/bootptab</file>, which

900

is a definition for all clients.

901

902

<sect1 id=troublebootp>Troubleshooting BOOTP daemon

903

The BOOTP daemon can also be started in debug mode if it is not

904

enabled in <file>inetd.conf</file>:

905

<example># bootpd -d7</example>

906

907

<sect id="bootdhcp">Configuration of the DHCP daemon

908

An example for <manref name="dhcpd.conf" section="5"> is available in

909

<file>/usr/share/doc/fai-doc/examples/etc</file>, which is working with

910

version 3.x of the DHCP daemon. Start using this example

911

and look at all options used therein.

912

913

914

One issue to bear in mind when configuring your DHCP daemon is that the

915

daemon needs to supply the nfsroot path to the client because

916

the kernel uses a path different from

917

<file>/srv/fai/nfsroot</file> by default.

918

919

920

If you make any changes

921

to the DHCP daemon configuration, you must restart the daemon.

922

<example># /etc/init.d/dhcp3-server restart</example>

923

Therefore it's recommended to only supply data into this configuration

924

file, which doesn't change frequently. By default, the DHCP daemon

925

writes its log files to <file>/var/log/daemon.log</file>.

926

The command <manref name="fai-chboot" section="8"> is used for creating a per host

927

configuration for the pxelinux environment.

928

929

930

<sect id="bootmesg">Boot messages

931

932

These are the messages when booting from floppy disk.

933

From FAI 3.2 the kernel and initrd will not fit onto a 1.4M floppy

934

disk any more.

935

936

GRUB loading stage2..............

937

< now the grub menu with multiple boot options is displayed >

938

BOOTING 'FAI-BOTH'

939

kernel (fd0)/vmlinuz-2.4.27 root=/dev/nfs ip=both

940

[Linux-bzImage, setup=0x1400, size=0xd8450]

941

942

Uncompressing Linux... OK, booting the Kernel.

943

Linux version &kver; (root@kueppers) (gcc version 2.95.4 20011002

944

.

945

.

946

.

947

</example>

948

After this, the rest of the boot messages will be equal to those when booting from

949

network card. When booting from network card with PXE you will see:

950

951

&bootexample;

952

953

When the copyright message of FAI is shown, the install client has mounted

954

the nfsroot<footnote> <file>/srv/fai/nfsroot</file> from the

955

install server </footnote> to the clients' root directory

956

<file>/</file>. This is the whole file system for the client at this

957

moment.

958

959

After <tt>task_confdir</tt> is executed, the configuration space is

960

mounted or received from a CVS repository.

961

962

Before the installation is started (<var>FAI_ACTION=install</var>) the computer

963

beeps three times. So, be careful when you hear three beeps

964

but you do not want to perform an installation!

965

966

<sect1 id=booterror>Troubleshooting the boot messages

967

968

This is the error message you will see, when your network card is

969

working, but the install server does not export the configuration

970

space directory to the install clients, mostly a problem of missing

971

permissions on the server side.

972

973

Begin: Mounting root file system... ...

974

eth0: link up

975

976

BusyBox v1.1.3 (Debian 1:1.1.3-4) Built-in shell (ash)

977

Enter 'help' for a list of built-in commands.

978

/bin/sh: can't access tty: job control turned off

979

(initramfs)

980

</example>

981

You will get a shell prompt and can look at the log files, for

982

examples <file>/live.log</file> or <file>/tmp/net-eth0.conf</file>.

983

984

Use the following command on the isntall server to see which directories are exported

985

from the install server (named faiserver):

986

<example>showmount -e faiserver</example>

987

988

989

990

The following error message indicates that your install client doesn't

991

get an answer from a DHCP server. Check your cables or start the

992

<manref name="dhcpd" section="8"> daemon with the debug flag enabled.

993

994

PXE-E51: No DHCP or BOOTP offers received

995

Network boot aborted

996

</example>

997

998

These are the messages when you are using the BOOTP method and no

999

BOOTP server replies.

1000

1001

Sending BOOTP requests ........ timed out!

1002

IP-Config: Retrying forever (NFS root)...

1003

</example>

1004

1005

If you get the following error message, the install kernel could not

1006

detect your network card, for example because of a missing driver:

1007

1008

Begin: Mounting root file system... ...

1009

Kernel panic - not syncing: Attempted to kill init!

1010

</example>

1011

Check the initrd in the nfsroot if the kernel driver of your network

1012

card is included there.

1013

1014

<sect id="sysinfo">Collecting other system information

1015

1016

1017

Now the clients have booted with <var>FAI_ACTION</var> set to sysinfo. Type

1018

<tt>ctrl-c</tt> to get a shell or use <tt>Alt-F2</tt> or

1019

<tt>Alt-F3</tt> and you will get another console terminal, if you have added <tt>createvt</tt>

1020

to <var>FAI_FLAGS</var>.

1021

1022

Remote login is available via the secure shell if <tt>sshd</tt> is

1023

added to <var>FAI_FLAGS</var>. The encrypted password is set with the

1024

variable <var>FAI_ROOTPW</var> in &mfnc; and defaults to "fai". You can

1025

create the encrypted password using <manref name="mkpasswd"

1026

section="1"> and use the <manref name="crypt" section="3"> or md5 algorithm. This

1027

is only the root password during the installation process, not for the

1028

new installed system. You can also log in without a password when

1029

using <var> SSH_IDENTITY</var>. To log in from your server to the

1030

install client (named demohost in this example) use:

1031

1032

<example>> ssh root@demohost

1033

Warning: Permanently added 'demohost,134.95.9.200' to the list of known hosts.

1034

root@demohost's password:

1035

</example>

1036

1037

1038

You now have a running Linux system on the install client

1039

without using the local hard disk. Use this as a rescue system if

1040

your local disk is damaged or the computer can't boot properly from

1041

hard disk. You will get a shell and you can execute various commands

1042

(<prgn>dmesg</prgn>, <prgn>lsmod</prgn>, <prgn>df</prgn>,

1043

<prgn>lspci</prgn>, ...). Look at the log file in

1044

<file>/tmp/fai</file>. There you can find much information about the boot

1045

process.

1046

1047

All log files from <file>/tmp/fai</file> are also written to the

1048

<var>$LOGSERVER</var> (if not defined: the server defined by

1049

<var>$SERVER</var> from <tt>get-boot-info</tt>) into the

1050

directory <tt>~fai/demohost/sysinfo/</tt><footnote>More general:

1051

<tt>~$LOGUSER/$HOSTNAME/$FAI_ACTION/</tt>. Two additional symbolic

1052

links are created. The symlink <file>last</file> points to the log

1053

directory of the last fai action performed. The symlinks

1054

<file>last-install</file> and <file>last-sysinfo</file> point to the

1055

directory with of the last corresponding action.

1056

1057

1058

Examples of the log

1059

files can be found on the FAI homepage.

1060

</footnote>

1061

1062

1063

FAI mounts all file systems it finds on

1064

the local disks read only. It also tells you on which partition a file

1065

<file>/etc/fstab</file> exists. When only one file system table is found, the

1066

partitions are mounted according to this information. Here's an

1067

example:

1068

1069

demohost:~# df

1070

Filesystem 1K-blocks Used Available Use% Mounted on

1071

rootfs 4099064 414088 3645296 11% /

1072

udev 10240 76 10164 1% /dev

1073

192.168.1.250:/srv/fai/nfsroot

1074

3905600 410976 3454944 11% /live/image

1075

unionfs 4099064 414088 3645296 11% /

1076

tmpfs 193464 3112 190352 2% /live/cow

1077

unionfs 4099064 414088 3645296 11% /dev/.static/dev

1078

unionfs 4099064 414088 3645296 11% /tmp/fai

1079

faiserver:/srv/fai/config

1080

3905600 410976 3454944 11% /var/lib/fai/config

1081

/dev/sda1 241116 74519 154149 33% /target

1082

/dev/sda9 4364212 139888 4179988 4% /target/home

1083

/dev/sda7 553376 16840 536536 4% /target/tmp

1084

/dev/sda8 2221628 275936 1832840 14% /target/usr

1085

/dev/sda6 577096 172924 374856 32% /target/var

1086

udev 10240 76 10164 1% /target/dev

1087

</example>

1088

1089

This method can be used as a rescue environment! In the

1090

future it will be possible to make backups or restore data to existing

1091

file systems. If you need a file system with read-write access use the

1092

<prgn>rwmount</prgn> command:

1093

1094

<example>demohost:~# rwmount /target/home</example>

1095

1096

<sect id=checkbootp>Checking parameters from BOOTP and DHCP servers

1097

1098

If the install client boots with action sysinfo, you can also

1099

check if all information from the BOOTP or DHCP daemons are received

1100

correctly. The received information is written to

1101

<file>/tmp/fai/boot.log</file>. An example of the result of a DHCP

1102

request can be found in <ref id="s1">.

1103

1104

1105

<sect id=reboot>Rebooting the computer

1106

At any time you can reboot the computer using the command

1107

<prgn>faireboot</prgn>, also if logged in from remote. If the

1108

installation hasn't finished, use <tt>faireboot -s</tt>, so the log

1109

files are also copied to the install server.

1110

1111

<chapt id=instprocess>Overview of the installation sequence

1112

1113

The following tasks are performed during an installation after the Linux kernel

1114

has booted on the install clients.

1115

1116

1117

1118

<item> Define classes </item>

1119

<item> Define variables </item>

1120

<item> Partition local disks </item>

1121

<item> Create and mount local file systems </item>

1122

<item> Install software packages </item>

1123

<item> Call site specific configuration scripts </item>

1124

<item> Save log files </item>

1125

<item> Reboot the new installed system </item>

1126

</enumlist>

1127

1128

1129

You can also define additional programs or scripts

1130

which will be run on particular

1131

occasions. They are called <tt>hooks</tt>. Hooks can add additional

1132

functions to the installation process or replace the default subtasks

1133

of FAI. So it's very easy to

1134

customize the whole installation process. Hooks are explained in

1135

detail in <ref id="hooks">.

1136

1137

1138

The installation time is determined by the amount of software but also

1139

by the speed of the processor and hard disk. Here are some sample

1140

times. All install clients have a 100Mbit network card installed.

1141

Using a 10 Mbit LAN does not increase the installation time

1142

considerably, so the network will not be the bottleneck when

1143

installing several clients simultaneously.

1144

1145

1146

Athlon XP1600+ , 896MB,SCSI disk, 1 GB software 6 min

1147

AMD-K7 500MHz , 320MB, IDE disk, 780 MB software 12 min

1148

PentiumPro 200MHz , 128MB, IDE disk, 800 MB software 28 min

1149

Pentium III 850MHz, 256MB, IDE disk, 820 MB software 10 min

1150

Pentium III 850MHz, 256MB, IDE disk, 180 MB software 3 min

1151

</example>

1152

1153

1154

<sect id=faimond>Monitoring the installation

1155

You can monitor the installation of all install clients with the

1156

command <manref name="faimond" section="8">. All clients check if this

1157

daemon is running on the install server (or the machine defined by the variable

1158

<var>monserver</var>. Then, a message is sent when a task starts and

1159

ends. The fai monitor daemon prints this messages to standard

1160

output. In the future, there will be a graphical frontend available.

1161

1162

<sect id=bootkernel>Booting the kernel

1163

The install client receives and loads the kernel and initial RAM disk. The kernel

1164

boots up and load the RAM disk. It does some hardware detection and

1165

then tries to figure where the root file system is located. When

1166

booting from network, this is determined by parameters from additional

1167

kernel parameters. When booting from CD-ROM or USB stick the kernel

1168

and initial RAM disk probes removable devices and tries to figure out

1169

where the root file system is located. This may also be a compressed

1170

file system (using squashfs).

1171

1172

After the root file system is mounted read only, it is made writeable

1173

by mounting a RAM disk via unionfs on top of it. So it's possible for

1174

programms or daemons to write to files inside a read-only mounted file system.

1175

We are using the package <tt>live-initramfs</tt> to mount the nfsroot and

1176

to make this file system writeable using unionfs.

1177

1178

<sect id=isetup>Set up FAI

1179

1180

1181

After the install client has booted, only the script

1182

<file>/usr/sbin/fai</file><footnote>Since the root file system on

1183

the clients is mounted via NFS, <prgn>fai</prgn> is located in

1184

<file>/srv/fai/nfsroot/usr/sbin</file> on the install server.

1185

</footnote> is executed. This is the main script which controls the

1186

sequence of tasks for FAI. No other scripts in

1187

<file>/etc/init.d/</file> are executed.

1188

1189

Additional parameters are received from the BOOTP or DHCP

1190

daemon and the configuration space if

1191

mounted via NFS from the install server to <file>/fai</file>. The

1192

setup is finished after additional virtual terminals are created and

1193

the secure shell daemon for remote access is started on demand.

1194

1195

<sect id=iclass>Defining classes, variables and loading kernel modules

1196

1197

Now the script <manref name="fai-class" section="1"> is used to define

1198

classes. Therefore several scripts in <file>/fai/class/</file> are

1199

executed to define classes. All scripts matching <tt>[0-9][0-9]*</tt>

1200

(they start with two digits)

1201

are executed in alphabetical order. Every word that these scripts

1202

print to the standard output are interpreted as class names.

1203

Scripts ending in <tt>.source</tt>

1204

are sourced, so they can define new classes by adding these classes to

1205

the variable <var>newclasses</var> (see <file>20-hwdetect.source</file> for an

1206

1207

example). The output of these scripts is ignored.

1208

These classes are defined for the

1209

install client. You can also say this client belongs to these

1210

classes. A class is defined or undefined and has no value. Only

1211

defined classes are of interest for an install client. The description

1212

of all classes can be found in

1213

<file>/usr/share/doc/fai-doc/classes_description.txt</file>. It is

1214

advisable to document the job a new class performs. Then, this

1215

documentation is the base for composing the whole configuration from classes.

1216

The scripts <prgn>20-hwdetect.source</prgn> loads kernel modules on

1217

demand.

1218

The complete description of all these scripts can be found in <ref id="cscripts">.

1219

1220

1221

After defining the classes, every file matching <tt>*.var</tt> with a

1222

prefix which matches a defined class is executed to define variables.

1223

There, you should define the variable <var>FAI_ACTION</var> and

1224

others. By default, <var>FAI_ACTION</var> is defined via the command

1225

<manref name="fai-chboot" section="8">.

1226

1227

1228

<sect id=ipartition>Partitioning local disks, creating file systems

1229

1230

For disk partitioning exactly one disk configuration file from

1231

<file>/fai/disk_config</file> is selected using classes. This file

1232

describes how all the local disks will be partitioned, where

1233

file systems should be created (and their types like ext2, ext3,

1234

reiserfs), and how they are mounted. It's also possible to preserve

1235

the disk layout or to preserve the data on certain partitions. It's

1236

done by the command <prgn>setup_harddisks</prgn>, which uses

1237

<prgn>sfdisk</prgn> for partitioning. The format of the configuration

1238

file is described in <ref id="diskconfig">.

1239

1240

1241

During the installation process all local file systems are mounted

1242

relative to <file>/target</file>. For example

1243

<file>/target/home</file> will become <file>/home</file> in the

1244

new installed system.

1245

1246

<sect id=ipackages>Installing software packages

1247

1248

When local file systems are created, they are all empty (except for

1249

preserved partitions). Now the Debian base system and all requested

1250

software packages are installed on the new file systems. First the

1251

base archive is unpacked, then the command

1252

<manref name="install_packages" section="8"> installs all packages using <manref

1253

name="apt-get" section="8"> or <manref name="aptitude" section="1">

1254

without any manual interaction needed. If a packages requires another

1255

package, both commands resolve this dependency by installing the

1256

required package.

1257

1258

1259

Classes are also used when selecting the configuration files in

1260

<file>/fai/package_config/</file> for software installation. The

1261

format of the configuration files is described in <ref

1262

id="packageconfig">.

1263

1264

<sect id=icscripts>Site specific configuration

1265

1266

After all requested software packages are installed, the system is

1267

nearly ready to go. But not all default configurations of the software

1268

packages will meet your site-specific needs. So you can call arbitrary

1269

scripts which adjust the system configuration. Therefore scripts which

1270

match a class name in <file>/fai/scripts</file> will be executed. If

1271

<file>/fai/scripts/</file><var>classname/</var> is a directory, all

1272

scripts that match <tt>[0-9][0-9]*</tt> in this directory are executed. So

1273

it is possible to have several scripts of different types (shell,

1274

cfengine, ...) to be executed for one class. FAI comes with some

1275

examples for these scripts, but you can write your own Bourne, bash,

1276

Perl, cfengine or expect scripts.

1277

1278

More information about these scripts are described in <ref id="cscripts">.

1279

1280

<sect id=isavelog>Save log files

1281

1282

When all installation tasks are finished, the log files are written to

1283

<tt>/var/log/fai/$HOSTNAME/install/</tt> <footnote>

1284

<file>/var/log/fai/localhost/install/</file> is a link to this

1285

directory. </footnote> on the new system and to the account on the

1286

install server if <var>$LOGUSER</var> is defined in &fc;. It is also

1287

possible to specify another host as log saving destination through

1288

the variable <var>$LOGSERVER</var>. Additionally, two symlinks will

1289

be created to indicated the last directory written to.

1290

By default log files will be copied to the log server using scp.

1291

1292

1293

You can use other methods to save logs to the remote server. The currently

1294

selected method is defined by the <var>$FAI_LOGPROTO</var> variable in

1295

file &fc;:

1296

1297

<tag>rsh</tag> <item>Use the rcp command to copy the log files to

1298

the log server.</item>

1299

1300

1301

This option saves logs to the remote FTP server defined by the

1302

<var>$LOGSERVER</var> variable (<var>$SERVER</var> value is used if

1303

not set). Connection to the FTP server is done as user

1304

<var>$LOGUSER</var> using password <var>$LOGPASSWD</var>. The FTP

1305

server log directory is defined in <var>$LOGREMOTEDIR</var>. These

1306

variables are also defined in file &fc;. You need write access for

1307

the <var>$LOGREMOTEDIR</var> on the FTP server.

1308

1309

All files in the directory <tt>/tmp/fai</tt> are copied to the

1310

FTP server following this example:

1311

<tt>ftp://<var>$LOGUSER</var>:<var>$LOGPASSWD</var>@<var>$LOGSERVER</var>/<var>$LOGREMOTEDIR</var>/</tt>.

1312

</item>

1313

<tag>none</tag> <item>Don't save the log file to the install server.</item>

1314

</taglist>

1315

1316

1317

<sect id=ireboot>Reboot the new installed system

1318

1319

At last the system is automatically rebooted if "reboot" was added to

1320

<var>FAI_FLAGS</var>. Normally this should boot the new installed

1321

system from its second boot device, the local hard disk. To skip

1322

booting from network card, you can use the command <manref

1323

name="fai-chboot" section="8"> to enable localboot. If using a boot

1324

floppy you have to remove the floppy from the floppy drive. Otherwise

1325

the installation would be performed again. Read <ref id="changeboot">

1326

for how to change the boot device.

1327

1328

<chapt id=plan>Plan your installation, and FAI installs your plans

1329

1330

Before starting your installation, you should spend a lot of time in

1331

planning your installation. When you're happy with your installation

1332

concept, FAI can do all the boring, repetitive tasks to turn your plans

1333

into reality. FAI can't do good installations if your concept is

1334

imperfect or lacks some important details. Start planning the

1335

installation by answering the following

1336

questions:

1337

1338

1339

<tag></tag> <item> Will I create a Beowulf cluster, or do I

1340

have to install some desktop machines? </item>

1341

<tag></tag> <item> What does my LAN topology look like? </item>

1342

<tag></tag> <item> Do I have uniform hardware?

1343

Will the hardware stay uniform in the future? </item>

1344

<tag></tag> <item> Does the hardware need a special kernel? </item>

1345

<tag></tag> <item> How should the hosts be named? </item>

1346

<tag></tag> <item> How should the local hard disks be partitioned? </item>

1347

<tag></tag> <item> Which applications will be run by the users? </item>

1348

<tag></tag> <item> Do the users need a queueing system? </item>

1349

1350

<tag></tag> <item> What software should be installed? </item>

1351

<tag></tag> <item> Which daemons should be started, and what

1352

should the configuration for these look like? </item>

1353

<tag></tag> <item> Which remote file systems should be mounted? </item>

1354

<tag></tag> <item> How should backups be performed? </item>

1355

<tag></tag> <item> Do you have sufficient power supply? </item>

1356

1357

<tag></tag> <item> How much heat do the cluster nodes produce and how are

1358

they cooled? </item>

1359

1360

</taglist>

1361

1362

You also have to think about user accounts, printers, a mail system, cron jobs,

1363

graphic cards, dual boot, NIS, NTP, timezone, keyboard layout,

1364

exporting and mounting directories via NFS and many other things. So,

1365

there's a lot to do before starting an installation. And remember

1366

that knowledge is power, and it's up to you to use it. Installation

1367

and administration is a process, not a product. FAI can't do things

1368

you don't tell it to do.

1369

1370

But you need not start from scratch. Look at all files and scripts

1371

in the configuration space. There are a lot of things you can use for

1372

your own installation.

1373

1374

A good paper with more aspects of building an infrastructure is

1375

1376

"Bootstrapping an Infrastructure".

1377

1378

<chapt id=config>Installation details

1379

1380

<sect id=c3>The configuration space

1381

1382

The configuration is the collection of information about how exactly to

1383

install a computer. The central configuration space for all install

1384

clients is located on the install server in <file>/srv/fai/config</file>

1385

and its subdirectories. This will be mounted by the install clients to

1386

<file>/var/lib/fai/config</file>. It's also possible to receive all the

1387

configuration data from a <manref name="cvs" section="1"> or

1388

subversion repository.

1389

The following subdirectories are present and include

1390

several files:

1391

1392

1393

<tag><tt>class/</tt></tag> <item> Scripts and files to

1394

define classes and variables and to load kernel modules. </item>

1395

1396

<tag><tt>disk_config/</tt></tag> <item> Configuration

1397

files for disk partitioning and file system creation. </item>

1398

1399

<tag><tt>debconf/</tt></tag> <item> This directory holds

1400

all <manref name="debconf" section="8"> data. The format is

1401

the same that is used by <manref name="debconf-set-selections"

1402

section="8">. </item>

1403

1404

<tag><tt>package_config/</tt></tag> <item> File with

1405

lists of software

1406

packages to be installed or removed. </item>

1407

1408

<tag><tt>scripts/</tt></tag> <item> Script for local site

1409

customization. </item>

1410

1411

<tag><tt>files/</tt></tag> <item> Files used by

1412

customization scripts.

1413

Most files are located in a subtree structure

1414

which reflects the ordinary directory tree. For example, the

1415

templates for <file>nsswitch.conf</file> are located in

1416

<file>/fai/files/etc/nsswitch.conf</file> and are named

1417

according to the classes that they should match:

1418

<file>/fai/files/etc/nsswitch.conf/NIS</file> is the version

1419

of <file>/etc/nsswitch.conf</file> to use for the NIS class.

1420

Note that the

1421

contents of the files directory are not automatically copied

1422

to the target machine, rather they must be explicitly

1423

copied by customization scripts using the <manref

1424

name="fcopy" section="8"> command. </item>

1425

1426

<tag><tt>files/packages/</tt></tag> <item>

1427

THE USE OF THIS DIRECTORY IS NOW OBSOLETE.

1428

</item>

1429

1430

<tag><tt>basefiles/</tt></tag> <item> Normally the file

1431

<file>/var/tmp/base.tgz</file> is extracted on the install client after

1432

the new file systems are created and before package are

1433

installed. This is a minimal base image, created right after calling

1434

debootstrap during the make-fai-nfsroot process on the install

1435

server. If you want to install another distribution than the nfsroot

1436

is, you can put a tar file into the subdirectory

1437

<file>basefiles/</file> and name it after a class. Then the command

1438

<manref name="ftar" section="8"> is used to extract the tar file based

1439

on the classes defined. This is done in task <tt>extrbase</tt>.

1440

1441

</item>

1442

1443

<tag><tt>hooks/</tt></tag> <item> Hooks are user defined

1444

programs or scripts, which are called during the

1445

installation process. </item>

1446

</taglist>

1447

1448

The main installation command <manref name="fai" section="8"> uses all these

1449

subdirectories in the order listed except for hooks. The FAI package

1450

contains examples

1451

for all these configuration scripts and files in

1452

<file>/usr/share/doc/fai-doc/examples</file>. Copy the configuration examples

1453

to the configuration space and start an installation. These files need

1454

not belong to the root account. You can change their ownership and

1455

then edit the configuration with a normal user account.

1456

1457

1458

# cp -a /usr/share/doc/fai-doc/examples/simple/* /srv/fai/config

1459

# chown -R fai /srv/fai/config

1460

</example>

1461

1462

These files contain simple configuration for some example

1463

hosts. Depending on the host name used, your computer will be

1464

configured as follows:

1465

1466

1467

<tag>demohost</tag> <item> A machine which needs only a small

1468

hard disk. This machine is configured with network (as DHCP

1469

client), and an account demo is created.

1470

1471

<tag>gnomehost</tag> <item> A GNOME desktop is installed, and

1472

the account demo is created.

1473

1474

<tag>other host names</tag> <item> Hosts with other host name will

1475

most notably use the classes FAIBASE, DHCPC and GRUB.

1476

1477

</taglist>

1478

Start looking at these examples and study them. Then change or add

1479

things to these examples. But don't forget to plan your own

1480

installation!

1481

1482

<sect id=tasks>The default tasks

1483

1484

After the kernel has booted, it mounts the root file system via NFS

1485

from the install server and <manref name="init" section="8"> starts the script

1486

<file>/usr/sbin/fai</file>. This script controls the

1487

sequence of the installation. No other scripts in

1488

<file>/etc/init.d/</file> are used.

1489

1490

1491

The installation script uses many subroutines, which are defined in

1492

<file>/usr/share/fai/subroutines</file>, and an operating system specific

1493

file <footnote><file>/usr/share/fai/subroutines-linux</file> for Linux,

1494

<file>/usr/share/fai/subroutines-sunos</file> for Solaris.</footnote>.

1495

1496

All important tasks of the

1497

installation are called via the subroutine <tt>task</tt>

1498

appended by the name of the task as an option (e.g. <tt>task

1499

instsoft</tt>). The subroutine <tt>task</tt> calls hooks with prefix

1500

name if available and then calls the default task (defined as

1501

<tt>task_name</tt> in <file>subroutines</file>). The default

1502

task and its hooks can be skipped on demand by using the subroutine

1503

<tt>skiptask()</tt>.

1504

1505

Now follows the description of all default tasks.

1506

1507

1508

<tag>confdir</tag> <item>The kernel appended parameters define

1509

variables, the syslog and kernel log daemon are started. The list of

1510

network devices is stored in <var>$netdevices</var>. Then additional

1511

parameters are fetched from a DHCP or BOOTP server and also

1512

additional variables

1513

are defined. The DNS resolver configuration file is created.

1514

1515

The location of the configuration space is defined by the variable

1516

<var>$FAI_CONFIG_SRC</var>. You can use NFS, cvs, svn or git to access the

1517

configuration space. See section <ref id="isetup"> for how to set the variable.

1518

1519

1520

1521

After that, the file

1522

<file>/fai/hooks/subroutines</file> is sourced if it exists. Using

1523

this file, you can define your own subroutines or override the

1524

definition of FAI's subroutines.

1525

1526

<tag>setup</tag> <item>This task sets the system time, all

1527

<var>FAI_FLAGS</var> are defined and two additional virtual

1528

terminals are opened on demand. A secure shell daemon is started

1529

on demand for remote logins.

1530

1531

<tag>defclass</tag> <item>Calls <manref name="fai-class"

1532

section="1"> to define classes using scripts and

1533

files in <file>/fai/class</file> and classes from

1534

<file>/tmp/fai/additional-classes</file>. </item>

1535

1536

<tag>defvar</tag> <item>Sources all files

1537

<file>/fai/class/*.var</file> for every defined class. If a hook

1538

has written some variable definitions to the file

1539

<file>/tmp/fai/additional.var</file>, this file is also

1540

sourced.</item>

1541

1542

<tag>action</tag> <item>Depending on the value of

1543

<var>$FAI_ACTION</var> this subroutine decides which action FAI

1544

should perform. The default available actions are:

1545

<tt>sysinfo</tt>, <tt>install</tt> and <tt>softupdate</tt>.

1546

If <var>$FAI_ACTION</var>

1547

has another value, a user defined action is called if a file

1548

<file>/fai/hooks/$FAI_ACTION</file> exists. So you

1549

can easily define your own actions.

1550

1551

1552

<tag>sysinfo</tag> <item>Called when no installation is

1553

performed but the action is <tt>sysinfo</tt>. It shows information

1554

about the detected hardware and mounts the local hard disks read

1555

only to <file>/target/<var>partitionname</var></file> or with regard to a

1556

<file>fstab</file> file found inside a partition. Log files are

1557

stored to the install server. </item>

1558

1559

<tag>install</tag> <item>This task controls the installation

1560

sequence. You will hear three beeps before the installation

1561

starts. The major work is to call other tasks and to save the

1562

output to <file>/tmp/fai/fai.log</file>. If you have any problems

1563

during installation, look at all files in

1564

<file>/tmp/fai/</file>. You can find examples of the log files

1565

for some hosts in the download directory of the FAI homepage.

1566

</item>

1567

1568

<tag>softupdate</tag> <item>This task, executed inside a running

1569

system via the <manref name="fai" section="8"> command line interface, performs a softupdate.

1570

See chapter <ref id=softupdate> for details. </item>

1571

1572

<tag>partition</tag> <item>Calls <prgn>setup_harddisk</prgn>

1573

to partition the hard disks. The task writes variable

1574

definitions for the root and boot partition and device (<var>$ROOT_PARTITION,

1575

$BOOT_PARTITION, $BOOT_DEVICE</var>) to

1576

<file>/tmp/fai/disk_var.sh</file> and creates an <file>fstab</file> file.</item>

1577

1578

1579

<tag>mountdisks</tag> <item>Mounts the created partitions

1580

according to the created <file>/tmp/fai/fstab</file> file relative to

1581

1582

1583

<tag>extrbase</tag> <item>Extracts a minimal system after

1584

that a chroot can be made into it. By default the base tar file

1585

<file>/var/tmp/base.tgz</file> will be extracted. The command

1586

<tt>ftar -1v -s $FAI/basefiles /</tt> is used for unpacking a

1587

different tar file depending on classes defined. This can be

1588

used for installing different Linux distributions than the one

1589

used for creating the nfsroot. The default file

1590

<file>base.tgz</file> is a snapshot of a basic Debian system created

1591

by <manref name="debootstrap" section="8"> </item>

1592

1593

<tag>mirror</tag> <item>If a local Debian mirror is accessed via NFS

1594

(when <var>$FAI_DEBMIRROR</var> is defined), this directory will

1595

be mounted to <var>$MNTPOINT</var>. </item>

1596

1597

<tag>debconf</tag> <item>Calls <manref name="fai-debconf"

1598

section="8"> to set the values for the debconf database. </item>

1599

1600

<tag>prepareapt</tag> <item>Set up resolv.conf and some

1601

other file, for the next task updatebase. </item>

1602

1603

<tag>updatebase</tag> <item>Updates the base packages of the

1604

new system and updates the list of

1605

available packages. It also fakes some commands (called diversions) inside

1606

the new installed system using <manref name="dpkg-divert"

1607

section="8">.

1608

</item>

1609

1610

<tag>instsoft</tag> <item>Installs the desired software

1611

packages using class files in

1612

<file>/fai/package_config/</file>. </item>

1613

1614

<tag>configure</tag> <item>Calls scripts in

1615

<file>/fai/scripts/</file> and its subdirectories for every

1616

defined class. </item>

1617

1618

<tag>finish</tag> <item>Unmounts all file systems in the

1619

new installed system and removes diversions of files

1620

using the command <prgn>fai-divert</prgn>.</item>

1621

1622

<tag>faiend</tag> <item>Wait for background jobs to finish

1623

(e.g. emacs compiling lisp files) and automatically reboots the install

1624

clients or waits for manual input before reboot. </item>

1625

1626

<tag>chboot</tag> <item>Changes the symbolic link on the install

1627

server which indicates which kernel image to load on the next

1628

boot from network card via TFTP. </item>

1629

1630

<tag>savelog</tag> <item>Saves log files to local disk and to

1631

the account <var>$LOGUSER</var> on <var>$LOGSERVER</var> (defaults to

1632

the install server). Currently the file <file>error.log</file>

1633

will not be copied to the log server. </item>

1634

1635

1636

</taglist>

1637

1638

1639

<sect id=s1>The setup routines of the install clients

1640

1641

After the subroutine <prgn>fai_init</prgn> has done some basic

1642

initialization (create RAM disk, read <file>fai.conf</file> and all

1643

subroutines definitions, set path, print copyright notice), the setup

1644

continues by calling the task <tt>confdir</tt> and the task

1645

<tt>setup</tt>. The command <prgn>get-boot-info</prgn> is called to

1646

get all information from the BOOTP or DHCP server. This command writes

1647

the file <file>/tmp/fai/boot.log</file>, which then is sourced to

1648

define the corresponding global variables. This is an example for this

1649

log file when using a DHCP server.

1650

1651

&bootlog;

1652

1653

Additional information is passed via the kernel command line or read

1654

from &fc;. When booting with PXE, command line parameters are created using <manref

1655

name="fai-chboot" section="8">. The variable <var>$FAI_FLAGS</var>

1656

contains a space separated list of flags. The following flags are

1657

known:

1658

1659

<tag>verbose</tag> <item> Create verbose output during

1660

installation. This should always be the first flag, so consecutive

1661

definitions of flags will be verbosely displayed. </item>

1662

1663

<tag>debug</tag> <item> Create debug output. No unattended

1664

installation is performed. During package installation you have to

1665

answer all questions of the postinstall scripts on the

1666

client's console. A lot of debug information will be printed

1667

out. This flag is only useful for FAI developers. </item>

1668

1669

<tag>sshd</tag> <item> Start the ssh daemon to enable remote

1670

logins. </item>

1671

1672

<tag>createvt</tag> <item> Create two virtual terminals and

1673

execute a bash if <tt>ctrl-c</tt> is typed in the console

1674

terminal. The additional terminals can be accessed by typing

1675

<tt>Alt-F2</tt> or <tt>Alt-F3</tt>. Otherwise no terminals are

1676

available and typing <tt>ctrl-c</tt> will reboot the install

1677

client. Setting this flag is useful for debugging. If you want an

1678

installation which should not be interruptible, do not set this

1679

flag. </item>

1680

1681

<tag>reboot</tag> <item> Reboot the install client after installation

1682

is finished without typing RETURN on the console. This is only useful if you can

1683

change the boot image or boot device automatically or your assembly robot

1684

can remove the boot floppy via remote control :-)

1685

Currently this should only be used when

1686

booting from network card. </item>

1687

</taglist>

1688

1689

1690

<sect id=classc> The class concept

1691

1692

1693

Classes determine which configuration file to choose from a list of

1694

available templates. Classes are used in all further tasks of the

1695

installation. To determine which config file to use, an install

1696

client searches the list of defined classes and uses all

1697

configuration files that match a class name. It's also possible to use

1698

only the configuration file with the highest priority since the order

1699

of classes define the priority from low to high. There are some

1700

predefined classes (DEFAULT, LAST and the host name), but classes can

1701

also be listed in a file or defined dynamically by scripts. So it's

1702

easy to define a class depending on the subnet information or on some

1703

hardware that is available on the install client.

1704

1705

The idea of using classes in general and using certain files matching

1706

a class name for a configuration is adopted from the installation

1707

scripts by Casper Dik for Solaris. This technique proved to be very

1708

useful for the SUN workstations, so I also use it for the fully

1709

automatic installation of Linux. One simple and very efficient feature

1710

of Casper's scripts is to call a command with all files (or on the

1711

first one) whose file

1712

names are also a class. The following loop implements this function

1713

in pseudo shell code:

1714

1715

1716

for class in $all_classes; do

1717

if [ -r $config_dir/$class ]; then

1718

your_command $config_dir/$class

1719

# exit if only the first matching file is needed

1720

fi

1721

done

1722

</example>

1723

Therefore it is possible to add a new file to

1724

the configuration without changing the script. This is because the

1725

loop automatically detects new configuration files that should be

1726

used. Unfortunately cfengine does not support this nice feature, so

1727

all classes being used in cfengine also need to be specified inside

1728

the cfengine scripts. Classes are very important for the fully

1729

automatic installation. If a client belongs to class <tt>A</tt>, we

1730

say the class <tt>A</tt> is defined. A class has no value, it is just

1731

defined or undefined. Within scripts, the variable <var>$classes</var>

1732

holds a space separated list with the names of all defined classes.

1733

Classes determine how the installation is performed. For example, an

1734

install client can be configured to become an FTP server by just adding

1735

the class <tt>FTP</tt> to it.

1736

1737

Mostly a configuration is created by only changing or appending the

1738

classes to which a client belongs, making the installation of a new

1739

client very easy. Thus no additional information needs to be added to

1740

the configuration files if the existing classes suffice for your needs.

1741

There are different possibilities to define classes:

1742

1743

<item>Some default classes are defined for every host:

1744

DEFAULT, LAST and its host name. </item>

1745

<item>Classes may be listed within a file. </item>

1746

<item>Classes may be defined by scripts. </item>

1747

</enumlist>

1748

1749

The last option is a very nice feature, since these scripts will

1750

define classes automatically. For example, several classes are

1751

defined only if certain hardware is identified. We use Perl and shell

1752

scripts to define classes. All names of classes, except the host name,

1753

are written in uppercase. They must not contain a hyphen, a hash or a

1754

dot, but may contain underscores. A description of all classes can be

1755

found in <file>/usr/share/doc/fai-doc/classes_description.txt</file>.

1756

1757

1758

host names should rarely be used for the configuration files in the

1759

configuration space. Instead, a class should be defined and

1760

then added for a given host. This is because most of the time the

1761

configuration data is not specific for one host, but can be shared

1762

among several hosts.

1763

1764

<sect id=s2> Defining classes

1765

1766

The task defclass calls the script <manref

1767

name="fai-class" section="1"> to define classes. Therefore, scripts

1768

matching <tt>[0-9][0-9]*</tt> in <tt>/fai/class</tt> are

1769

executed. Additionally, a file with the host name may contain a list of

1770

classes.

1771

For more information on defining class, read the manual pages for <manref

1772

name="fai-class" section="1">.

1773

1774

The list of all defined classes is stored in the variable

1775

<var>$classes</var> and saved to

1776

<file>/tmp/fai/FAI_CLASSES</file>. The list of all classes is

1777

transfered to <prgn>cfengine</prgn>, so it can use them too. The

1778

script <file>10-base-classes</file> (below is a stripped version) is used to

1779

define classes depending on the host name. First this script defines

1780

the class with the name of the hardware architecture in uppercase

1781

letters.

1782

1783

# cat 10-base-classes

1784

1785

# echo architecture and OS name in upper case. Do NOT remove these two lines

1786

uname -s | tr '[:lower:]' '[:upper:]'

1787

dpkg --print-installation-architecture | tr /a-z/ /A-Z/

1788

1789

[ -f /boot/RUNNING_FROM_FAICD ] && echo "FAICD"

1790

1791

# use a list of classes for our demo machine

1792

case $HOSTNAME in

1793

demohost)

1794

echo "FAIBASE GRUB DHCPC DEMO" ;;

1795

gnomehost)

1796

echo "FAIBASE GRUB DHCPC DEMO XORG GNOME";;

1797

*)

1798

echo "FAIBASE GRUB DHCPC" ;;

1799

esac

1800

</example>

1801

1802

The script <tt>20-hwdetect.source</tt> uses the default Debian commands

1803

to detect hardware and to load some kernel modules. If

1804

some specific hardware is found, it can also define a new class for it.

1805

You can find messages from modprobe in <file>/tmp/fai/kernel.log</file> and

1806

on the fourth console terminal by pressing <tt>Alt-F4</tt>.

1807

1808

<sect id=classvariables> Defining variables

1809

1810

The task <tt>defvar</tt> defines the variables for the install

1811

client. Variables are defined by scripts in

1812

<tt>class/*.var</tt>. All global variables can be set in

1813

<file>DEFAULT.var</file>. For certain groups of hosts use a class file

1814

or for a single host use the file

1815

<var>$HOSTNAME</var><tt>.var</tt>. Also here, it's useful to study all

1816

the examples.

1817

1818

The following variables are used in the examples and may also be useful

1819

for your installation:

1820

1821

1822

<tag>FAI_ACTION</tag> <item> Set the action fai should

1823

perform. Normally this is done by <manref name="fai-chboot"

1824

section="8">. If you can't use this command and are not using a

1825

BOOTP server, define it in the script <file>LAST.var</file>.

1826

1827

<tag>CONSOLEFONT</tag> <item> Is the font which is loaded during

1828

installation by <manref name="consolechars" section="8">. </item>

1829

1830

<tag>KEYMAP</tag> <item> Defines the keyboard map files in

1831

<file>/usr/share/keymaps</file> and <file>$FAI/files</file>. You

1832

need not specify the complete path, since this file will be located

1833

automatically. </item>

1834

1835

<tag>ROOTPW</tag> <item> The encrypted root password for the new

1836

system. You can use <manref name="crypt" section="3"> or md5

1837

encryption for the password. </item>

1838

1839

<tag>UTC</tag> <item> Set hardware clock to UTC if

1840

<tt>$UTC=yes</tt>. Otherwise set clock to local time. See <manref

1841

name="clock" section="8"> for more information. </item>

1842

1843

<tag>TIMEZONE</tag> <item> Is the file relative to

1844

<file>/usr/share/zoneinfo/</file> which indicates your time

1845

zone. </item>

1846

1847

<tag>MODULESLIST</tag> <item> Can be a multi line

1848

definition. List of modules (including kernel parameters) which are

1849

loaded during boot of the new system (written to /etc/modules).

1850

</item>

1851

1852

</taglist>

1853

1854

<sect id=diskconfig>Hard disk configuration

1855

1856

The script <prgn>setup_harddisks</prgn> partitions and formats

1857

the local disks. It uses all configuration files in

1858

<file>/fai/disk_config/</file> which are also defined as classes.

1859

Lines beginning with # are comments. The config file

1860

<file>/fai/disk_config/FAIBASE</file> is a generic description for

1861

one hard disk (IDE or SCSI), which most installations should be able to adapt. If you

1862

can't partition your hard disk using this script <footnote>Currently

1863

this script uses the command <tt>sfdisk(8)</tt>, which isn't available

1864

on SUN SPARC, IA64 and PowerPC. </footnote>, use a hook instead. The hook should

1865

write the new partition table, create the file systems and create the

1866

files <file>/tmp/fai/fstab</file> and <file>/tmp/fai/disk_var.sh</file>, which

1867

contains definitions of boot and root partitions.

1868

1869

1870

The following example is a configuration for the first IDE disk <tt>disk1</tt>

1871

and for the second SCSI disk <tt>disk2</tt> The numbering of the disks comes

1872

from the order in <file>/proc/partitions</file>.

1873

1874

1875

# <type> <mount point> <size in MB> [mount options] [;extra options]

1876

1877

disk_config disk1

1878

1879

primary / 200 defaults,errors=remount-ro

1880

logical /home 100-300

1881

logical /scratch1 10- defaults,nosuid ; -i 15000 -m 0

1882

1883

1884

disk_config disk2

1885

1886

primary /tmp 300-500 rw ;ext2

1887

primary /backup preserve2 rw

1888

logical swap 50-100

1889

logical /scratch2 100-300 rw ;-m 30

1890

logical - preserve7

1891

logical /var 100 ;-j

1892

logical /var/tmp preserve9 ;format

1893

primary /tmp/mytmp -300

1894

</example>

1895

1896

Every disk configuration starts with the command <tt>disk_config</tt>

1897

followed by <tt>diskX</tt> where <tt>X</tt> is the number of the HDD. The

1898

Linux device names <file>/dev/hda</file> and <file>/dev/sda</file>

1899

correspond to <tt>disk1</tt>, <tt>disk2</tt> corresponds to

1900

<file>/dev/hdb</file> and <file>/dev/sdb</file> and so on.

1901

1902

After <tt>disk_config</tt> one line containing the type, mount point

1903

and size is added for each partition on the harddisk. Mount options

1904

and additional parameters for <prgn>mke2fs</prgn> -- separated from

1905

the mount options by a semicolon -- can be added.

1906

1907

1908

<tag>Type</tag> <item> There are two types of partitions: primary

1909

and logical. Primary partitions are bootable, but there is a maximum

1910

of four primary partitions on each disk. The Linux root file system

1911

must be of this type.

1912

1913

All other partitions are called logical. Because logical partitions

1914

are gathered internally in one big primary partition, only three

1915

primary partitions can be used if logical partitions are defined.

1916

Normally only one primary partition for the root file system is

1917

created and all others are logical, like <tt>disk1</tt> in the example above.

1918

1919

<tag>Mount point</tag> <item> The mount point is the full path

1920

(beginning with a slash) for the file system. The value <tt>swap</tt>

1921

defines a Linux swap partition. Both types will be automatically

1922

added to <file>/etc/fstab</file>. A dash (<tt>-</tt>) indicates that

1923

the partition will not be mounted and can be used for other types of

1924

file systems (FAT, NTFS, UFS, MINIX, ...)

1925

1926

<tag>Size</tag> <item> This is the size of the partition in

1927

megabytes. This value is rounded up to fit to a cylinder

1928

number. There are several ways of defining the size:

1929

1930

"200" means about 200MB, no more no less

1931

"100-300" sets a 100MB minimum and a 300MB maximum

1932

"10-" sets a minimum of 10MB and a maximum of the disk size

1933

"-300" sets a minimum of 1MB and a 300MB maximum

1934

</example>

1935

1936

By default, a new file system (currently of type ext2 or swap) will be

1937

created, and all data on the partition is lost. The meaning of

1938

<tt>preserve<no></tt> will be described later.

1939

1940

Calculating the partition size:

1941

If an interval is defined for several partition sizes, the script

1942

maximizes the values by preserving the ratio between them.

1943

1944

1945

<tag>Mount options</tag> <item> The mount options will be copied

1946

to <file>/etc/fstab</file>. An empty field sets the option to

1947

<tt>defaults</tt> (see <manref name="mount" section="8">).

1948

1949

1950

<tag>Extra options</tag> <item> The last field is a space

1951

separated extra options list. The following options are known:

1952

1953

boot : Make this partition the boot-partition (the

1954

Linux root file system is the default).

1955

-i <bytes> : bytes per inode (ext2/3 only)

1956

-m <blocks> : reserved blocks percentage (ext2/3 only)

1957

-j : Create the file system with an ext3 journal.

1958

-c : Check for bad blocks.

1959

ext2 : Flag as ext2 instead of auto in /etc/fstab.

1960

ext3 : Flag as ext3 instead of auto in /etc/fstab.

1961

swap : swap partition

1962

dosfat16 : DOS 16 bit FAT file system

1963

winfat32 : Win95 FAT32 file system

1964

reiser : Create a ReiserFS file system, not an ext2.

1965

xfs : XFS

1966

format : Always format even if preserve is specified.

1967

writable : Mounts a preserved partition writable.

1968

lazyformat : Do not format if partition has not moved.

1969

</example>

1970

1971

The order of the extra options is not relevant. For more information

1972

see <manref name="mke2fs" section="8">.

1973

1974

Thus, we have the following interactions between <tt>-j</tt>,

1975

<tt>ext2</tt> and <tt>ext3</tt> :

1976

1977

<no option> : An ext2 fs flagged as auto in the fstab

1978

-j : An ext3 fs flagged as auto in the fstab.

1979

ext2 : An ext2 fs flagged as ext2 in the fstab.

1980

-j ext2 : An ext3 fs flagged as ext2 in the fstab.

1981

-j ext3 : An ext3 fs flagged as ext3 in the fstab.

1982

ext3 : An ext2 fs flagged as ext3 in the fstab. !!BAD!!

1983

</example>

1984

1985

Using <tt>auto</tt> in the fstab for ext3 file systems enables a

1986

non-ext3-enabled kernel or tool to cope with these partitions.

1987

</taglist>

1988

1989

1990

It is possible to preserve the size and even the existing

1991

data on a partition. To preserve only the

1992

partition size, the number of the partition must be unchanged and the

1993

size must be specified as <tt>preserve<no></tt> The number

1994

<tt><no></tt> is the device number (as in <file>/dev/hda<no></file>,

1995

or see the output of <prgn>df</prgn>) of the partition. Primary partitions

1996

are numbered from one to four, the numbers for logical partitions

1997

begin at five.

1998

1999

Problems were reported (February 2003) when using more than two primary

2000

partitions and trying to preserve a logical partition. If you have

2001

this problem, try to use only two primary partitions.

2002

2003

In the following example, the partition numbers (= device number) are also

2004

shown for disk <tt>disk2</tt>:

2005

2006

2007

primary /tmp 300-500 # 1

2008

primary /backup preserve2 # 2

2009

logical swap 50-100 # (3) 5

2010

logical /scratch2 100-300 # (3) 6

2011

logical - preserve7 # (3) 7

2012

logical /var 100 # (3) 8

2013

logical /var/tmp preserve9 # (3) 9

2014

primary /tmp/mytmp -300 # 4

2015

</example>

2016

2017

2018

The first two partitions are of type primary, so they get the numbers

2019

1 and 2. The logical partitions start at 5 and the last gets number

2020

9. All logical partitions define the primary partition 3, but this

2021

number is not used. So if you want to preserve <file>/dev/hda7</file>

2022

you have to insert a minimum of two logical partitions before it.

2023

2024

2025

Lazyformating partitions is another method to preserve partitions

2026

after they were formatted once. This is useful to design systems

2027

which can be reinstalled without loosing data on partitions like

2028

<file>/home</file> or <file>/var/log</file> or

2029

<file>/var/lib/mysql</file> or whatever. You can even lazyformat

2030

the swap partition to gain a minor installation speed improvement

2031

after the first installation!

2032

2033

2034

If you have a separate <file>/boot</file> partition, you must add the

2035

extra option <tt>boot</tt> to make it your boot partition. Otherwise

2036

your system will not be bootable. By default (if no boot option was

2037

specified) the root partition (<file>/</file>) will become the boot

2038

partition. <prgn>setup_harddisks</prgn> will write some variables

2039

containing the information about boot partition and boot device to

2040

<file>/tmp/fai/disk_var.sh</file>.

2041

2042

2043

<sect id=packageconfig>Software package configuration

2044

<!--MT: This section is pretty much a chaos:

2045

- which commands belong to which package tools

2046

- you say something about PRELOADRM and PRELOAD commands, but give no example

2047

and don't list them otherwise

2048

-->

2049

The script <prgn>install_packages</prgn> installs the selected software

2050

packages. It uses all configuration files in <file>/fai/package_config</file>

2051

whose file name matches a defined class. The syntax is very

2052

simple.

2053

2054

2055

# an example package class

2056

2057

PACKAGES taskinst

2058

german

2059

2060

PACKAGES aptitude

2061

adduser netstd ae

2062

less passwd

2063

2064

PACKAGES remove

2065

gpm xdm

2066

2067

PACKAGES aptitude GRUB

2068

lilo- grub

2069

2070

PACKAGES dselect-upgrade

2071

ddd install

2072

a2ps install

2073

</example>

2074

2075

Comments are starting with a hash (#) and are ending at the end of

2076

the line. Every command begins with the word <tt>PACKAGES</tt>

2077

followed by a command name. The command defines which command will be

2078

used to install the packages named after this command. The list of all

2079

available commands can be listed using <tt>install_packages -H</tt>.

2080

Supported package tools are: <tt>aptitude, apt-get, smart, y2pmsh,

2081

yast, yum, urpm, rpm</tt>

2082

2083

2084

<tag>hold:</tag> <item> Put a package on hold. This package will

2085

not be handled by dpkg, e.g not upgraded. </item>

2086

2087

<tag>install:</tag> <item> Install all packages that are specified

2088

in the following lines. If a hyphen is appended to the package name

2089

(with no intervening space), the package will be removed, not

2090

installed. All package names are checked for misspellings.

2091

Any package which does not exist, will be removed from the list of

2092

packages to install. So be careful not to misspell any package names. </item>

2093

2094

<tag>remove:</tag> <item> Remove all packages that are specified in

2095

the following lines. Append a + to the package name if the package

2096

should be installed. </item>

2097

2098

<tag>taskinst:</tag> <item> Install all packages belonging to the

2099

tasks that are specified in the following lines using <manref

2100

name="tasksel" section="1">. You can also use <tt>aptitude</tt> for

2101

installing tasks. </item>

2102

2103

<tag>aptitude:</tag> <item> Install all packages with

2104

the command <prgn>aptitude</prgn>. This will be the default in the future

2105

and may replace apt-get and taskinst. Aptitude can also install task

2106

packages. </item>

2107

2108

<tag>aptitude-r:</tag> <item> Same as aptitude with option

2109

<tt>--with-recommends</tt>.

2110

2111

<tag>unpack:</tag> <item> Download package and unpack only. Do not

2112

configure the package.

2113

2114

<tag>dselect-upgrade</tag> <item> Set package selections using the

2115

following lines and install or remove the packages specified. These

2116

lines are the output of the command <tt>dpkg --get-selections</tt>.

2117

</taglist>

2118

2119

2120

Multiple lines with lists of space separated names of packages follow

2121

the PACKAGES lines. All dependencies are resolved. Packages with

2122

suffix <tt>-</tt> (eg. <tt>lilo-</tt>) will be removed instead of

2123

installed. The order of the packages is of no matter.

2124

2125

A line which contains the <tt>PRELOADRM</tt> commands, downloads a

2126

file using <manref name="wget" section="1"> into a directory before

2127

installing the packages. Using the <tt>file:</tt> URL, this file is copied

2128

from <var>$FAI_ROOT</var> to the download directory.

2129

For example the package

2130

<prgn>realplayer</prgn> needs an archive to install the software, so

2131

this archive is downloaded to the directory <file>/root</file>. After

2132

installing the packages this file will be removed. If the file

2133

shouldn't be removed, use the command <tt>PRELOAD</tt> instead.

2134

2135

2136

It's possible to append a list of class names after the command for

2137

apt-get. So this <tt>PACKAGE</tt> command will only be executed when

2138

the corresponding class is defined. So you can combine many small

2139

files into the file DEFAULT. WARNING! Use this feature only

2140

in the file DEFAULT to keep everything simple. See this file for some

2141

examples.

2142

2143

2144

If you specify a package that does not exist this package will be

2145

removed from the installation list when the command <tt>install</tt>

2146

is used. You can also test all software package

2147

configuration files with the utility <prgn>chkdebnames</prgn>, which

2148

is available in <file>/usr/share/doc/fai-doc/examples/utils/</file>.

2149

2150

> chkdebnames stable /srv/fai/config/package_config/*

2151

</example>

2152

2153

<sect id=cscripts>Scripts in <tt>/fai/scripts</tt>

2154

2155

The default set of scripts in <file>/fai/scripts</file> is only an example. But

2156

they should do a reasonable job for your installation. You can edit them

2157

or add new scripts to match your local needs.

2158

2159

The command <manref name="fai-do-scripts" section="1"> is called to

2160

execute all scripts in this directory. If a directory with a class

2161

name exists, all scripts matching <file>[0-9][0-9]*</file> are executed in

2162

alphabetical order. So it's possible to use scripts of different

2163

languages (shell, cfengine, Perl,..) for one class.

2164

2165

<sect1 id=shell>Shell scripts

2166

2167

Most scripts are Bourne shell scripts. Shell scripts are useful if the

2168

configuration task only needs to call some shell commands or create a

2169

file from scratch. In order not to write many short scripts, it's

2170

possible to distinguish classes within a script using the command

2171

<tt>ifclass</tt>. For copying files with classes, use the command

2172

<manref name="fcopy" section="8">. If you want to extract an archive

2173

using classes, use <manref name="ftar" section="8">.

2174

But now have a look at the scripts and see what they are doing.

2175

2176

<sect1 id=perl>Perl scripts

2177

Currently no Perl script are used in the simple examples for modifying the system

2178

configuration.

2179

2180

<sect1 id=expect>Expect scripts

2181

Currently no expect scripts are used in the simple examples for modifying the system

2182

configuration.

2183

2184

<sect1 id=cfengine>Cfengine scripts

2185

2186

Cfengine has a rich set of functions to edit existing configuration

2187

files, e.g <tt>LocateLineMatching, ReplaceAll, InsertLine,

2188

AppendIfNoSuchLine, HashCommentLinesContaining</tt>. But it can't

2189

handle variables which are undefined. If a variable is undefined,

2190

the whole cfengine script will abort. Study the examples that are

2191

included in the fai package.

2192

2193

More information can be found in the manual page <manref

2194

name="cfengine" section="8"> or at the cfengine homepage

2195

<httpsite>www.cfengine.org</httpsite>.

2196

2197

2198

<sect id=changeboot>Changing the boot device

2199

2200

Changing the boot sequence is normally done in the BIOS setup. But

2201

you can't change the BIOS from a running Linux system as far as I

2202

know. If you know how to perform this, please send me an email. But there's

2203

another way of swapping the boot device of a running Linux system.

2204

<!--MT: recently, there has been some discussion on linux-fai, add a link to the

2205

archives-->

2206

2207

So, normally the boot sequence of the BIOS will remain unchanged and

2208

your computer should always boot first from its network card and the

2209

second boot device should be the local disk. Then, it will

2210

get an install kernel image from the install server, when an

2211

installation should be performed, or we can tell pxelinux to boot from

2212

local disk. This is done using <manref name="fai-chboot" section="8">.

2213

2214

Here is how to set up a 3Com network card as first boot device.

2215

Enable LAN as first boot device in the BIOS.

2216

2217

2218

Boot From LAN First: Enabled

2219

Boot Sequence : C only

2220

</example>

2221

2222

Then enter the MBA setup of the 3Com network card and change it as follows:

2223

2224

Default Boot Local

2225

Local Boot Enabled

2226

Message Timeout 3 Seconds

2227

Boot Failure Prompt Wait for timeout

2228

Boot Failure Next boot device

2229

</example>

2230

2231

This will enable the first IDE hard disk as second boot device after

2232

the network card.

2233

2234

If booting from a FAI floppy disk, another solution can be used to skip a

2235

re-installation if the BIOS is configured to boot from the floppy disk

2236

first and you are not there to remove the floppy disk:

2237

2238

# lilo -R ...

2239

</example>

2240

will instruct the FAI floppy to boot from the hard disk only once (see

2241

<manref name="lilo" section="8">). Thus after this first reboot, the FAI

2242

floppy disk can be used for another FAI installation.

2243

2244

2245

<sect id=hooks>Hooks

2246

2247

Hooks let you specify functions or programs which are run at certain

2248

steps of the installation process. Before a default task is called,

2249

FAI searches for existing hooks for this task and executes them. As you

2250

might expect, classes are also used when calling hooks. Hooks are

2251

executed for every defined class. You only have to create the hook

2252

with the name for the desired class and it will be used.

2253

If several hooks for a task exists, they are called in the order

2254

defined by the classes.

2255

If <tt>debug</tt> is included in <var>$FAI_FLAG</var> the option

2256

<tt>-d</tt> is passed to all hooks, so you can debug your own hooks.

2257

If some default tasks should be skipped, use the subroutine

2258

<tt>skiptask</tt> and a list of default tasks as parameters. The

2259

example <file>partition.DISKLESS</file> skips some default tasks.

2260

2261

2262

2263

The directory <file>/fai/hooks/</file> contains all hooks. The file

2264

name of a hook consists of a task name as a prefix and a class name,

2265

separated by a dot. The prefix describes the time when the hook is

2266

called, if the class is defined for the install client. For example,

2267

the hook <file>partition.DISKLESS</file> is called for every client

2268

belonging to the class <tt>DISKLESS</tt> before the local disks would

2269

be partitioned. If it should become a diskless client, this hook

2270

can mount remote file systems via NFS and create a <tt>/tmp/fai/fstab</tt>.

2271

After that, the installation process will not try to partition and

2272

format a local hard disk, because a file <file>/tmp/fai/fstab</file>

2273

already exists.

2274

2275

A hook of the form <tt>hookprefix.classname</tt> can't define

2276

variables for the installation script, because it's a subprocess. But

2277

you can use any binary executable or any script you wrote. Hooks that

2278

have the suffix <tt>.source</tt> (e.g. <file>partition.DEFAULT.source</file>) must

2279

be Bourne shell scripts and are sourced. So it's possible to

2280

redefine variables for the installation scripts.

2281

2282

2283

In the first part of FAI, all hooks with prefix <tt>confdir</tt> are called.

2284

Since the configuration directory <file>/fai</file> is mounted in the

2285

default task <tt>confdir</tt>, the hooks for this task are the only

2286

hooks located in <var>$nfsroot</var><file>/fai/hooks</file> on the

2287

install server. All other hooks are found in

2288

<file>$FAI_CONFIGDIR/hooks</file> on the install server.

2289

2290

2291

All hooks that are called before classes are defined can only use the

2292

following classes: <tt>DEFAULT $HOSTNAME LAST</tt>. If a hook for

2293

class <tt>DEFAULT</tt> should only be called if no hook for class

2294

<var>$HOSTNAME</var> is available, insert these lines to the default

2295

hook:

2296

2297

2298

hookexample.DEFAULT:

2299

2300

#! /bin/sh

2301

2302

# skip DEFAULT hook if a hook for $HOSTNAME exists

2303

scriptname=$(basename $0 .DEFAULT)

2304

[-f /fai/hooks/$scriptname.$HOSTNAME ] && exit

2305

# here follows the actions for class DEFAULT

2306

.

2307

.

2308

</example>

2309

2310

2311

Some examples for what hooks could be used:

2312

2313

<list>

2314

<item> Use <prgn>ssh</prgn> in the very beginning to verify that

2315

you mounted the configuration from the correct server and not a

2316

possible spoofing host.</item>

2317

2318

<item> Do not mount the configuration directory, instead get a

2319

compressed archive via HTTP or from floppy disk and extract it into a

2320

new RAM disk, then redefine <var>$FAI_LOCATION</var>.</item>

2321

2322

<item> Load kernel modules before classes are defined

2323

in <file>/fai/class</file>. </item>

2324

2325

<item> Send an email to the administrator if the installation is finished.</item>

2326

2327

<item> Install a diskless client and skip local disk

2328

partitioning. See <file>hooks/partition.DISKLESS</file>.</item>

2329

2330

<item> Partition the hard disk on an IA64 system, which needs a

2331

special partition table type that must be created with <manref

2332

name="parted" section="8">.</item>

2333

</list>

2334

2335

<sect id=errors>Looking for errors

2336

If the client can't successfully boot from the network card, use

2337

<manref name="tcpdump" section="8"> to look for Ethernet packets

2338

between the install server and the client. Search also for entries in

2339

several log files made by <manref name="tftpd" section="8">,

2340

<manref name="dhcpd3" section="8"> or <manref name="bootpd" section="8">:

2341

2342

<example>egrep "tftpd|bootpd|dhcpd" /var/log/*</example>

2343

2344

If the installation process finishes, the hook

2345

<file>savelog.LAST.source</file> searches all log files for common errors and

2346

writes them to the file <file>error.log</file>. So, you should first

2347

look into this file for errors. Also the file <file>status.log</file>

2348

give you the exit code of the last command executed in a script. To be

2349

sure, you should look for errors in all log files.

2350

2351

Sometimes the installation seems to stop, but often there's only a

2352

postinstall script of a software package that requires manual input

2353

from the console. Change to another virtual terminal and look which

2354

process is running with tools like <manref name="top" section="1"> and <manref

2355

name="pstree" section="1">. You can add <tt>debug</tt> to

2356

<tt>FAI_FLAGS</tt> to make the installation process show all output

2357

from the postinst scripts on the console and get its input also from the

2358

console. Don't hesitate to send an email to the mailing list or to

2359

<email>fai@informatik.uni-koeln.de</email> if you have any

2360

questions. Sample log files from successfully installed computers are

2361

available on the FAI homepage.

2362

2363

<chapt id=beowulf>How to build a Beowulf cluster using FAI

2364

2365

2366

This chapter describes the details about building a Beowulf

2367

cluster using &dgl; and FAI. This chapter was written for FAI

2368

version 2.x for Debian woody and was not yet updated. The example

2369

configuration files were removed from the fai packages after FAI 2.8.4.

2370

2371

For more information about the Beowulf

2372

concept look at <httpsite>www.beowulf.org</httpsite>.

2373

2374

<sect id=beoplan> Planning the Beowulf setup

2375

2376

The example of a Beowulf cluster consists of one master node and 25

2377

clients. A big rack was assembled which all the cases were put into. A

2378

keyboard and a monitor, which are connected to the master server

2379

most of the time, were also put into the rack. But since we have very long

2380

cables for a monitor and a keyboard, they can also be connected to all

2381

nodes if something has to be changed in the BIOS, or when looking for

2382

errors when a node does not boot. Power supply is another topic you

2383

have to think about. Don't connect many nodes to one power cord and

2384

one outlet. Distribute them among several breakout boxes and outlets.

2385

And what about the heat emission? A dozen nodes in a small room can

2386

create too much heat, so you will need an air conditioner. Will the

2387

power supplies of each node go to stand-by mode or are all nodes

2388

turned on simultaneously after a power failure?

2389

2390

2391

All computers in this example are connected to a Fast Ethernet switch. The master node

2392

(or master server) is called nucleus. It has two network

2393

cards. One for the connection to the external Internet, one for the

2394

connection to the internal cluster network. If connected from the

2395

external Internet, it's called nucleus, but the cluster nodes

2396

access the master node with the name atom00, which is a name

2397

for the second network interface. The master server is also the

2398

install server for the computing nodes. A local Debian mirror will be

2399

installed on the local harddisk. The home directories of all user

2400

accounts are also located on the master server. It will be exported via

2401

NFS to all computing nodes. NIS will be used to distribute account,

2402

host, and printer information to all nodes.

2403

2404

2405

All client nodes atom01 to atom25 are connected via

2406

the switch with the second interface card of the master node. They can

2407

only connect to the other nodes or the master, but can't communicate

2408

to any host outside their cluster network. So, all services (NTP, DNS,

2409

NIS, NFS, ...) must be available on the master server. I chose the class C

2410

network address 192.168.42.0 for building the local Beowulf

2411

cluster network. You can replace the subnet 42 with any other number

2412

you like. If you have more than 253 computing nodes, choose a class A

2413

network address (10.X.X.X).

2414

2415

2416

In the phase of preparing the installation, you have to boot the first

2417

install client many times, until there's no fault in your configuration

2418

scripts. Therefore you should have physical access to the master

2419

server and one client node. So, connect both computers to a switch

2420

box, so one keyboard and monitor can be shared among both.

2421

2422

<sect id=master> Set up the master server

2423

2424

The master server will be installed by hand if it is your first

2425

computer installed with Debian. If you already have a host running

2426

Debian, you can also install the master server via FAI. Create a

2427

partition on <file>/files/scratch/debmirror</file> for the local

2428

Debian mirror with more than &mirrorsize; GB space available.

2429

2430

<sect1 id=beonetworkmaster> Set up the network

2431

2432

Add the following lines for the second network card to

2433

<file>/etc/network/interfaces</file>:

2434

2435

# Beowulf cluster connection

2436

auto eth1

2437

iface eth1 inet static

2438

address 192.168.42.250

2439

netmask 255.255.255.0

2440

broadcast 192.168.42.255

2441

</example>

2442

2443

Add the IP addresses for the client nodes. The FAI package has an

2444

example for this <file>/etc/hosts</file> file:

2445

2446

# create these entries with the Perl one liner

2447

# perl -e 'for (1..25) {printf "192.168.42.%s atom%02s\n",$_,$_;}'

2448

2449

# Beowulf nodes

2450

# atom00 is the master server

2451

192.168.42.250 atom00

2452

192.168.42.1 atom01

2453

192.168.42.2 atom02

2454

</example>

2455

2456

You can give the internal Beowulf network a name when you add this

2457

line to <file>/etc/networks</file>:

2458

<example>beowcluster 192.168.42.0</example>

2459

2460

2461

Activate the second network interface with: <tt>/etc/init.d/networking start</tt>.

2462

2463

<sect1 id=beonis> Setting up NIS

2464

2465

Add a normal user account <var>tom</var> which is the person who edits

2466

the configuration space and manages the local Debian mirror:

2467

<example># adduser tom

2468

# addgroup linuxadmin

2469

</example>

2470

2471

This user should also be in the group <var>linuxadmin</var>.

2472

2473

# adduser tom linuxadmin

2474

</example>

2475

2476

First set the NIS domainname name by creating the file

2477

<file>/etc/defaultdomain</file> and call <manref name="domainname" section="8">.

2478

To initialize the master server as NIS server call <tt>/usr/lib/yp/ypinit -m</tt>.

2479

Also edit <file>/etc/default/nis</file> so the host becomes a NIS

2480

master server.

2481

Then, copy the file <file>netgroup</file> from the examples directory

2482

to <file>/etc</file> and edit other files there. Adjust access to the

2483

NIS service.

2484

2485

<example># cat /etc/ypserv.securenets

2486

# Always allow access for localhost

2487

255.0.0.0 127.0.0.0

2488

# This line gives access to the Beowulf cluster

2489

255.255.255.0 192.168.42.0

2490

</example>

2491

2492

Rebuild the NIS maps:

2493

2494

2495

You will find much more information about NIS in the

2496

<file>NIS-HOWTO</file> document.

2497

2498

<sect1 id=beomirror> Create a local Debian mirror

2499

2500

Now the user <var>tom</var> can create a local Debian mirror on

2501

<file>/files/scratch/debmirror</file> using

2502

<prgn>mkdebmirror</prgn>. You can add the option <tt>--debug</tt> to

2503

see which files are received. This will

2504

need about &mirrorsize; GB disk space for Debian 3.0 (aka woody). Export this

2505

directory to the netgroup <tt>@faiclients</tt> read only.

2506

Here's the line for <file>/etc/exports</file>

2507

<tt>/files/scratch/debmirror *(ro)</tt>

2508

2509

<sect1 id=fai1> Install FAI package on the master server

2510

2511

Add the following packages to the install server:

2512

<example>nucleus:/# apt-get install ntp tftpd-hpa dhcp3-server \

2513

nfs-kernel-server etherwake fai

2514

nucleus:/# tasksel -q -n install dns-server

2515

nucleus:/# apt-get dselect-upgrade

2516

</example>

2517

Configure NTP so that the master server will have the correct system time.

2518

2519

2520

It's very important to use the internal network name <var>atom00</var>

2521

for the master server (not the external name <var>nucleus</var>) in

2522

<file>/etc/dhcp3/dhcpd.conf</file> and &mfnc;. Replace

2523

the strings FAISERVER with <tt>atom00</tt> and uncomment the following line in &mfnc;

2524

so the Beowulf nodes can use the name for connecting to their master server.

2525

2526

NFSROOT_ETC_HOSTS="192.168.42.250 atom00"

2527

</example>

2528

2529

<sect1 id=bootp1> Prepare network booting

2530

2531

Set up the install server daemon as described in <ref

2532

id="pxeboot">. If you will have many cluster nodes (more than about

2533

10) and you will use <tt>rsh</tt> in &fc; raise the number of connects

2534

per minute to some services in <file>inetd.conf</file>:

2535

2536

shell stream tcp nowait.300 root /usr/sbin/tcpd /usr/sbin/in.rshd

2537

login stream tcp nowait.300 root /usr/sbin/tcpd /usr/sbin/in.rlogind

2538

</example>

2539

2540

The user <var>tom</var> should have permission to create the

2541

symlinks for booting via network card, so change the group and add

2542

some utilities.

2543

2544

<example># chgrp -R linuxadmin /srv/tftp/fai; chmod -R g+rwx /srv/tftp/fai

2545

# cp /usr/share/doc/fai-doc/examples/utils/* /usr/local/bin

2546

</example>

2547

2548

Now, the user <var>tom</var> sets the boot image for the first beowulf

2549

node.

2550

<example>fai-chboot -IFv atom01</example>

2551

2552

Now boot the first client node for the first

2553

time. Then start to adjust the configuration for your client

2554

nodes. Don't forget to build the kernel for the cluster nodes using

2555

<manref name="make-kpkg" section="8"> and store it in <file>/srv/fai/config/files/packages</file>.

2556

2557

<sect id=beotools> Tools for Beowulf clusters

2558

2559

The following tools are useful for a Beowulf cluster:

2560

2561

2562

<tag> tlink <item> Change the symbolic link that points to

2563

the kernel image for booting from a network card. Only used

2564

when you boot using BOOTP.</item>

2565

2566

<tag> all_hosts <item> Print a list of all hosts, print

2567

only the hosts which respond to a ping or the hosts which

2568

do not respond. The complete list of hosts is defined by the

2569

netgroup <tt>allhosts</tt>. Look at

2570

<file>/usr/share/doc/fai-doc/examples/etc/netgroup</file> for an

2571

example.</item>

2572

2573

<tag>rshall<item>Execute a command on all hosts which are

2574

up via rsh. Uses <prgn>all_hosts</prgn> to get the list of all

2575

hosts up. You can also use the <manref name="dsh" section="1">

2576

command (dancer's shell, or distributed shell).

2577

2578

<tag>rup<item> The command <manref name="rup" section="1">

2579

shows briefly the CPU load of every host.

2580

2581

<tag>clusterssh<item> The package clusterssh allows you to

2582

control multiple ssh or rsh sessions at the same time.

2583

2584

</taglist>

2585

These are some common tools for a cluster environment:

2586

2587

2588

<tag>rgang</tag> <item> For a huge cluster try

2589

<prgn>rgang</prgn>. It's is a tool which executes commands on or

2590

distributes files to many nodes. It uses an algorithm to build a

2591

tree-like structure to allow the distribution processing time to

2592

scale very well to 1000 or more nodes (available at

2593

<httpsite>fermitools.fnal.gov/</httpsite>

2594

<httppath>abstracts/rgang/abstract.html</httppath>). </item>

2595

2596

<tag>jmon</tag><item>For observing the resources of all

2597

clients (CPU, memory, swap,...) you can use <manref

2598

name="jmon" section="1"> which installs a simple daemon on

2599

every cluster node. </item>

2600

2601

<tag>ganglia</tag><item>This toolkit is very good for monitoring

2602

your cluster with a nice web frontend. Available at

2603

<httpsite>ganglia.sourceforge.net/</httpsite> </item>

2604

2605

</taglist>

2606

2607

<sect id=wol> Wake on LAN with 3Com network cards

2608

2609

Wake on LAN is a very nice feature to power on a computer without

2610

having physical access to it. By sending a special ethernet packet to

2611

the network card, the computer will be turned on. The following things

2612

have to be done, to use the wake on LAN (WOL) feature.

2613

2614

2615

<item>Connect the network card to the Wake-On-LAN connector on the

2616

motherboard using a 3 pin cable.</item>

2617

<item>My ASUS K7M motherboard has a jumper called

2618

<tt>Vaux (3VSBSLT)</tt> which allows to select the voltage supplied to add-in

2619

PCI cards. Set it to <tt>Add 3VSB</tt> (3 Volt stand by).</item>

2620

<item>Turn on the wake on LAN feature in BIOS</item>

2621

<item>For a 3Com card using the 3c59x driver you must enable the

2622

WOL feature using the kernel module option <tt>enable_wol</tt>.

2623

</enumlist>

2624

2625

To wake up a computer use the command <manref name="ether-wake" section="8">.

2626

Additional information is available from

2627

<httpsite>www.scyld.com/</httpsite><httppath>expert/wake-on-lan.html</httppath>.

2628

2629

<chapt id=arch>FAI on other architectures and distributions

2630

If you want to use FAI on other architectures than i386 you might need

2631

to take care of some things yourself.

2632

2633

These are things that may have to be changed on other architectures:

2634

2635

2636

<tag> make-nfsroot.conf <item> FAI_DEBOOTSTRAP_OPTS must be adopted to the

2637

architecture you're using.

2638

2639

<tag> task partition: <item> Currently setup_harddisks

2640

needs the command <manref name="sfdisk" section="8">. If

2641

this is not available then write a short shell script which

2642

uses <manref name="parted" section="8">, to partition the disks and

2643

for creating the file <file>fstab</file>. Alternatively you can use a

2644

hook (see <ref id="hooks">) to format and mount your partitions.

2645

2646

<tag> Boot loader: <item> There are scripts for setting up

2647

<manref name="lilo" section="8"> and <manref name="grub" section="8">. Here you may

2648

add support for your specific boot loader.

2649

</taglist>

2650

2651

If you want to serve multiple nfsroot directories on one FAI server,

2652

you need to create specific config directories in <file>/etc</file>

2653

for fai, like <file>/etc/fai-sarge</file> and

2654

<file>/etc/fai-etch</file>. Then you need to set the

2655

<var>NFSROOT</var> variables to different directories and run

2656

<tt>make-fai-nfsroot -c /etc/fai-sarge</tt>.

2657

2658

<sect id=amd64>FAI on AMD64

2659

No problems. Have a look at

2660

<httpsite>www.informatik.uni-koeln.de</httpsite><httppath>/fai/download/amd64/</httppath>

2661

2662

<sect id=powerpc>FAI on PowerPC

2663

There's some stuff on <httpsite>www.layer-acht.org</httpsite><httppath>/fai</httppath>.

2664

Most notably there are hooks for partitioning and config-files to

2665

setup bootloaders for oldworld and newworld.

2666

2667

<sect id=ia64>FAI on IA64

2668

There's one big IA64 Beowulf cluster running which was installed with

2669

FAI. Only the partitioning part has to be replaced by a short script,

2670

since sfdisk is not available on IA64.

2671

2672

<sect id=alpha>FAI on Alpha

2673

There is a Mini-HowTo available at

2674

<httpsite>www.aei.mpg.de</httpsite><httppath>/~stefgru/fai/</httppath>

2675

2676

<sect id=odists>FAI for Suse, Redhat and Gentoo

2677

Many people are interested in FAI for other (mostly RPM based) Linux

2678

distributions. I made some research and it should not be much work to

2679

implement it. But I need more help to implement it. If you are

2680

interested and would like to help me, please send an email to

2681

<email>fai@informatik.uni-koeln.de</email>.

2682

2683

<sect id=sparc>FAI on SUN SPARC hardware running Linux

2684

2685

Although FAI is architecture independent, there are some packages which

2686

are only available for certain architectures (e.g. silo, sparc-utils).

2687

2688

SUN SPARC computers can boot from their boot prompt and don't need a

2689

boot floppy. To boot a SUN use: <example>boot net:dhcp - ip=::::::dhcp</example>

2690

2691

2692

You have to convert the kernel image from ELF format to a.out

2693

format. Use the program <prgn>elftoaout</prgn> (mentioned in

2694

the FAQ). The symlink to the kernel image to be booted is not the host

2695

name. Look at the FAQ at

2696

<httpsite>www.ultralinux.org</httpsite> for more information

2697

and <httpsite>www.sparc-boot.org/</httpsite>.

2698

.

2699

2700

A success report is available at

2701

<httpsite>www.opossum.ch/</httpsite><httppath>fai/</httppath>

2702

and a HOWTO and a lot of examples can be found at

2703

<httpsite>toolbox.rutgers.edu/</httpsite><httppath>~amurphy/fai</httppath>.

2704

2705

<sect id=solaris>FAI for Solaris

2706

FAI has also been ported for use with SUN Solaris OS installations

2707

in cooperation with Solaris jumpstart.

2708

Get the FAI sources and change to the <file>sunos</file> directory. There

2709

you can call <tt>make</tt> which creates the tarball

2710

<file>/tmp/fai-solaris.tar.gz</file>. You have to read the file

2711

<file>README.sunos</file> and have some knowledge about Solaris

2712

jumpstart.

2713

2714

The file format of the configuration files in <file>disk_config</file> and

2715

<file>package_config</file> are different than those for Linux.

2716

2717

<chapt id=advanced>Advanced FAI

2718

2719

<sect id="dirinstall">Installing into a mounted directory for chroot and virtualization

2720

If you have some chroot environments to install, or a virtualization environment where

2721

you neither can nor want to run a normal Debian Installer in to

2722

get to a working system (for example, Xen guest domains), there is the

2723

FAI action <tt>dirinstall</tt>.

2724

2725

By calling

2726

<example>fai <options> dirinstall <target-directory></example>

2727

and using either the option <tt>-c <classes></tt> or

2728

<tt>-N</tt> you get a FAI installation, without the partitioning

2729

action, right into the target directory. The host name for the target

2730

installation can be specified using <tt>-u <host-name></tt>

2731

2732

This, for example, can be used to combine FAI with the tool <tt>xen-tools</tt>, which

2733

helps you to build Xen guest domains. <tt>xen-tools</tt> are very nice for

2734

generating configuration files and block devices for new guests based on simple

2735

commands and/or configuration files, but they can only assign one role per installation

2736

for customization.

2737

FAI-users need and want more, as they are used to have the class system.

2738

They get them even in xen-tools installations, by using the following code as

2739

a xen-tools role script:

2740

2741

2742

#!/bin/sh

2743

TARGET=$1

2744

CMD="fai -N -v -u ${hostname} dirinstall $TARGET"

2745

echo running $CMD

2746

$CMD

2747

</example>

2748

2749

Then, you will want to set the variable <example>install=0</example> in the xen-tools config for

2750

that host(in previous versions of xen-tools, this was <tt>no-install=1</tt>).

2751

2752

<sect id=softupdate>Using FAI for updates

2753

FAI is even usable for system updates, using the same configuration

2754

as if initially installing. System update means updating the running

2755

system without doing a re-installation. An updated client will almost

2756

look like a newly installed machine, though all local data is

2757

preserved (except of course newer configuration files introduced in

2758

the FAI config).

2759

2760

<sect1 id=aboutsoftupdate>How does a softupdate work?

2761

Softupdates use the same configuration files as a new FAI installation. They

2762

even use the default FAI commands, so they behave nearly in

2763

the same way as an installation, though some things are different:

2764

<list>

2765

<item>By default the old list of classes (created during the

2766

initial installation) is used, so <prgn>fai-class</prgn>

2767

is not called to define a new list of classes. This can be

2768

changed by calling <tt>fai -N softupdate</tt>.</item>

2769

2770

<item>No partitioning and file system creation is performed.</item>

2771

<item>The basesytem isn't bootstrapped.</item>

2772

<item>FAI skips tasks only useful when installing, such as setting up

2773

a keymap or starting special daemons.</item>

2774

<item>FAI doesn't prevent software packages to (re-)start daemons.</item>

2775

<item>FAI doesn't reboot at the end of a softupdate.</item>

2776

</list>

2777

Except these changes, things are the same as when installing a new computer:

2778

2779

<item>Define classes (by default use old list) and variables.</item>

2780

<item>Update the installed packages.</item>

2781

<item>Install new software.</item>

2782

<item>Call configuration scripts.</item>

2783

<item>Save the logfiles.</item>

2784

</enumlist>

2785

</sect1>

2786

2787

<sect1 id=runsoftupdate>How to run a softupdate

2788

As softupdates use the same infrastructure as a FAI installation, you even

2789

start them by using the same command <manref name="fai" section="8"> which is used for

2790

installation:

2791

2792

/usr/sbin/fai softupdate

2793

</example>

2794

starts a softupdate.

2795

2796

<sect2 id=startsoftupdate>How to do mass softupdates

2797

Probably you don't want to run to each client and start a softupdate there

2798

locally, so a mechanism to start an update there has to be thought of.

2799

2800

<sect3 id=cronsoftupdate>Cron

2801

One possible solution is to use crontab entries on the clients to start an

2802

update, but in big installations you have to consider including a random-delay

2803

mechanism, because too many updates at the same time may produce too much

2804

traffic on your network.

2805

2806

<sect3 id=remotesoftupdate>Starting a softupdate remotely

2807

If you want more control when exactly a softupdate is run on the clients

2808

and maybe want to monitor it while it is running, you can install remote root

2809

login mechanisms on your clients, preferably using ssh in connection with a

2810

authorized key for root logins.

2811

Tools like <tt>clusterssh</tt> allow you to login onto a group of clients at

2812

once and run <tt>/usr/sbin/fai softupdate</tt> there, while the results can be

2813

seen immediately in the terminals started for each host.

2814

</sect2>

2815

</sect1>

2816

2817

<sect1 id=confsoftupdate>How to write a configuration suitable for softupdates

2818

When you want to do softupdates, you have to be even more careful when

2819

writing your configuration: it has to be idempotent, i.e.

2820

running all the scripts twice should result in the same system configuration

2821

as running them once. Some things to keep an eye on:

2822

<list>

2823

<item>Never blindly append to files:

2824

2825

echo $SOMETHING >> /etc/fstab

2826

</example>

2827

is almost certainly wrong. Either check manually if the

2828

line already exists before appending or use

2829

cfengine's <tt>AppendIfNoSuchLine</tt> statement

2830

instead.</item>

2831

2832

<item>Make use of FAI's environment variables to determine what to do in

2833

your configuration scripts! Some of the most important ones:

2834

2835

2836

<item>points to the client's rootdir.

2837

In case of softupdates: <tt>/</tt></item>

2838

<tag><var>ROOTCMD</var></tag>

2839

<item>contains a command for <tt>chrooting</tt>

2840

into the client. This is empty when doing

2841

softupdates (as <tt>/</tt> is already our

2842

root...).</item>

2843

<tag><var>FAI_ACTION</var></tag>

2844

<item>contains the currently executed action:

2845

2846

<tag><tt>install</tt></tag>

2847

<item>when installing.</item>

2848

<tag><tt>softupdate</tt></tag>

2849

<item>when updating</item>

2850

</taglist>

2851

</taglist>

2852

2853

<item>Restart daemons if needed: most daemons only read their

2854

configuration when starting; if you modify it, you need to

2855

make them reload it using

2856

2857

$ROOTCMD invoke-rc.d $somedaemon reload

2858

</example>

2859

or even restart them

2860

2861

$ROOTCMD invoke-rc.d $somedaemon restart

2862

</example>

2863

when the configuration for <tt>$somedaemon</tt> has been

2864

changed<footnote>You can for example use <manref

2865

name="fcopy" section="8">'s

2866

<tt>postinst</tt> script support for doing this; if other

2867

things than <tt>fcopy</tt> modify your conffiles, you have to

2868

keep track of the changes yourself.</footnote>.

2869

</item>

2870

2871

<item>Other things like scheduling a reboot if a new kernel is installed</item>

2872

</list>

2873

</sect1>

2874

2875

<sect1 id=localconfsoftupdate>What if there are locally changed conffiles?

2876

Short: there shouldn't be any!

2877

Long: if you are using FAI <tt>softupdate</tt> to

2878

update client's configuration, you shouldn't do any local changes on

2879

the install clients, because they may be lost while updating. Backup

2880

copies are done by fcopy only on the local disk (by default, they are

2881

written to the same directory as the original file, with

2882

<tt>.pre_fcopy</tt> appended); if you want to save them together with

2883

the logfiles,

2884

2885

FAI_BACKUPDIR=$LOGDIR/backup

2886

</example>

2887

in <tt>class/DEFAULT.var</tt> will do the job.

2888

2889

<sect2 id=detectlocalchanges>How to detect locally changed files?

2890

If you are playing with local configuration changes despite all the warnings

2891

contained in this section, there must be a way to check what has been

2892

changed locally. A simple approach would be to use <tt>debsums -e</tt>,

2893

but this method fails miserably if you modify conffiles in your FAI scripts,

2894

because it only checks against the version contained in the Debian package. A

2895

better proposal is to setup/abuse <tt>tripwire</tt> or <tt>integrit</tt> to scan

2896

for local changes and notify you about them.

2897

</sect2>

2898

2899

</sect1>

2900

</sect>

2901

</chapt>

2902

2903

<chapt id=hints>Various hints

2904

2905

This chapter has various hints which may not always be explained in great

2906

detail.

2907

2908

When using HTTP access to a Debian mirror, the local <tt>/var</tt>

2909

partition on all install clients must be big enough to keep the

2910

downloaded Debian packages. Do not try with less than 250 Mbytes

2911

unless you know why. You can limit the number of packages installed at

2912

a time with the variable <var>$MAXPACKAGES</var>.

2913

2914

You can shorten some scripts by using one single fcopy

2915

command <tt>fcopy -r /</tt>.

2916

2917

If you rebuild the nfsroot, you will create a new ssh host key inside

2918

the nfsroot. Then logging in to an install client may fail, because

2919

the host key changes. You can use this:

2920

2921

2922

ssh -o StrictHostKeyChecking=no root@installclient

2923

</example>

2924

2925

2926

2927

You can calculate the IP subnet adress (which is used in

2928

&mfnc; for the variable <var>FAICLIENTS</var> by using

2929

the nice tool ipcalc. Following example gives you the notation for a

2930

class C network (16) when the server netork interface has the IP address

2931

123.45.6.123

2932

2933

ipcalc -nb 123.45.6.123 16|grep Network:

2934

</example>

2935

2936

You can merge two directories which contain configuration

2937

information, if one is a global one, and the other a local one. We use

2938

it to merge the templates from the FAI package, and our local

2939

configuration, which contains encrypted passwords and other

2940

information that should not be readable by others.

2941

If you remove a file in your local configuration, do not forget to

2942

remove this file also in the configuration space, otherwise it will

2943

still be used.

2944

2945

After calling <prgn>set-disk-info</prgn>, a list of all local hard disks is

2946

stored in <var>$disklist</var> and <var>$device_size</var>

2947

contains a list of disk devices and their sizes.

2948

2949

2950

2951

Use <prgn>fai-divert -a</prgn> if a postinst script calls a

2952

configuration program, e.g. the postinst script for package apache calls

2953

apacheconfig, which needs manual input. You can fake the configuration

2954

program so the installation can be fully automatic. But don't forget

2955

to use <prgn>fai-divert -R</prgn> to remove all faked scripts.

2956

2957

2958

During the installation you can execute commands

2959

inside the newly installed system in a chroot environment by using <tt>chroot /target</tt>

2960

or just <tt>$ROOTCMD</tt> followed by the command you want to call; for

2961

example <tt>$ROOTCMD dpkg -l</tt> shows the packages installed on

2962

the new system.

2963

2964

2965

<!--MT: has been said already

2966

The only task which has to be done manually for new hardware is to

2967

assign the MAC address to a host name and to an IP address, and to define

2968

classes for this host if the existing configuration files are not generic

2969

enough to deal with this new host.

2970

2971

There's a tradeoff between writing a few large configuration scripts,

2972

or many short scripts, one for each class. Large scripts can

2973

distinguish classes by using case statements, the <tt>ifclass</tt>

2974

test or with class mechanisms for <tt>cfengine</tt> scripts.

2975

2976

-->

2977

If your computer can't boot from the network card, you do not always need to boot

2978

from floppy. Add the class

2979

<tt>FAI_BOOTPART</tt> and FAI will automatically create a

2980

lilo or grub entry for

2981

booting the FAI bootfloppy from this partition. So you can start the

2982

re-installation without a boot floppy. This will also make the test

2983

phase shorter, since booting from hard disk is much faster than booting

2984

from floppy. You can also set a password for this boot menu.

2985

2986

2987

<sect id=difai>Using FAI after an Installation with the Debian-Installer

2988

On <httpsite>www.layer-acht.org</httpsite><httppath>/fai</httppath> you

2989

will find an example how to fully automatically install a system using the Debian

2990

Installer (d-i) in conjunction with FAI's new softupdate (see <ref id=softupdate>).

2991

2992

<!--MT: has been said already

2993

2994

You should get the program <prgn>imggen</prgn>,<footnote>Available at

2995

the download page <httpsite>www.ltsp.org</httpsite> or from the FAI

2996

download page &faidownload;.</footnote> if you like to boot from a

2997

3Com network card using the BOOTP protocol. This executable converts

2998

netboot images created by <manref name="mknbi-linux" section="8">, so

2999

they can be booted by network cards from 3Com. Put that executable in

3000

your path (e.g. <file>/usr/local/bin</file>)

3001

3002

<sect id=functions>Useful functions for advanced administrators

3003

3004

3005

<tag>fai-divert</tag> <item> Add or remove a file to the list of diversions

3006

and replace the file with a dummy script. This is useful when a

3007

postinst script needs manual input. At the end of the installation all

3008

diversions are removed. </item>

3009

3010

<tag>skiptask</tag> <item> This given list of tasks are

3011

skipped. For use e.g. in <file>partition.DISKLESS</file>. </item> </taglist>

3012

-->

3013

3014

</book>

3015

</debiandoc>

3016

3017

<!-- Keep this comment at the end of the file

3018

Local variables:

3019

mode: sgml

3020

sgml-omittag:t

3021

sgml-shorttag:t

3022

sgml-minimize-attributes:nil

3023

sgml-always-quote-attributes:t

3024

sgml-indent-step:2

3025

sgml-indent-data:nil

3026

sgml-parent-document:nil

3027

sgml-exposed-tags:nil

3028

sgml-declaration:nil

3029

sgml-local-catalogs:nil

3030

sgml-local-ecat-files:nil

3031

End:

3032

-->

3033

3034

3035

3036

3037

3038

3039

3040

3041

3042

3043