/mandos/trunk : revision 83

1

<?xml version="1.0" encoding="UTF-8"?>

1

<?xml version='1.0' encoding='UTF-8'?>

2

<?xml-stylesheet type="text/xsl"

3

href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>

2

4

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"

3

"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [

5

"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [

4

6

<!ENTITY VERSION "1.0">

5

7

<!ENTITY COMMANDNAME "mandos">

6

<!ENTITY TIMESTAMP "2008-08-30">

7

8

]>

8

9

10

10

11

11

<title>Mandos Manual</title>

12

13

<productname>Mandos</productname>

12

<title>&COMMANDNAME;</title>

13

14

<productname>&COMMANDNAME;</productname>

14

15

<productnumber>&VERSION;</productnumber>

15

<date>&TIMESTAMP;</date>

16

17

18

<firstname>Björn</firstname>

67

68

<refname><command>&COMMANDNAME;</command></refname>

69

70

Gives encrypted passwords to authenticated Mandos clients

70

Sends encrypted passwords to authenticated Mandos clients

71

</refpurpose>

72

</refnamediv>

73

74

75

76

<command>&COMMANDNAME;</command>

77

<arg>--interface<arg choice="plain">NAME</arg></arg>

78

<arg>--address<arg choice="plain">ADDRESS</arg></arg>

79

80

<arg>--priority<arg choice="plain">PRIORITY</arg></arg>

81

<arg>--servicename<arg choice="plain">NAME</arg></arg>

82

<arg>--configdir<arg choice="plain">DIRECTORY</arg></arg>

83

<arg>--debug</arg>

84

</cmdsynopsis>

85

86

<command>&COMMANDNAME;</command>

87

88

<arg>-a<arg choice="plain">ADDRESS</arg></arg>

89

90

<arg>--priority<arg choice="plain">PRIORITY</arg></arg>

91

<arg>--servicename<arg choice="plain">NAME</arg></arg>

92

<arg>--configdir<arg choice="plain">DIRECTORY</arg></arg>

93

<arg>--debug</arg>

94

</cmdsynopsis>

95

96

<command>&COMMANDNAME;</command>

97

98

99

100

</group>

101

</cmdsynopsis>

102

103

<command>&COMMANDNAME;</command>

104

<arg choice="plain">--version</arg>

105

</cmdsynopsis>

106

107

<command>&COMMANDNAME;</command>

108

<arg choice="plain">--check</arg>

77

<arg choice='opt'>--interface<arg choice='plain'>IF</arg></arg>

78

<arg choice='opt'>--address<arg choice='plain'>ADDRESS</arg></arg>

79

80

<arg choice='opt'>--priority<arg choice='plain'>PRIORITY</arg></arg>

81

<arg choice='opt'>--servicename<arg choice='plain'>NAME</arg></arg>

82

<arg choice='opt'>--configdir<arg choice='plain'>DIRECTORY</arg></arg>

83

<arg choice='opt'>--debug</arg>

84

</cmdsynopsis>

85

86

<command>&COMMANDNAME;</command>

87

88

<arg choice='opt'>-a<arg choice='plain'>ADDRESS</arg></arg>

89

90

<arg choice='opt'>--priority<arg choice='plain'>PRIORITY</arg></arg>

91

<arg choice='opt'>--servicename<arg choice='plain'>NAME</arg></arg>

92

<arg choice='opt'>--configdir<arg choice='plain'>DIRECTORY</arg></arg>

93

<arg choice='opt'>--debug</arg>

94

</cmdsynopsis>

95

96

<command>&COMMANDNAME;</command>

97

98

</cmdsynopsis>

99

100

<command>&COMMANDNAME;</command>

101

<arg choice='plain'>--version</arg>

102

</cmdsynopsis>

103

104

<command>&COMMANDNAME;</command>

105

<arg choice='plain'>--check</arg>

109

106

</cmdsynopsis>

110

107

</refsynopsisdiv>

111

108

115

112

<command>&COMMANDNAME;</command> is a server daemon which

116

113

handles incoming request for passwords for a pre-defined list of

117

114

client host computers. The Mandos server uses Zeroconf to

118

announce itself on the local network, and uses TLS to

119

communicate securely with and to authenticate the clients. The

120

Mandos server uses IPv6 to allow Mandos clients to use IPv6

121

link-local addresses, since the clients will probably not have

122

any other addresses configured (see <xref linkend="overview"/>).

123

Any authenticated client is then given the stored pre-encrypted

124

password for that specific client.

115

announce itself on the local network, and uses GnuTLS to

116

communicate securely with and to authenticate the clients.

117

Mandos uses IPv6 link-local addresses, since the clients are

118

assumed to not have any other addresses configured. Any

119

authenticated client is then given the pre-encrypted password

120

for that specific client.

125

121

</para>

126

122

127

123

</refsect1>

131

127

132

128

<para>

133

129

The purpose of this is to enable <emphasis>remote and unattended

134

rebooting</emphasis> of client host computer with an

135

<emphasis>encrypted root file system</emphasis>. See <xref

136

linkend="overview"/> for details.

130

rebooting</emphasis> of any client host computer with an

131

<emphasis>encrypted root file system</emphasis>. The client

132

host computer should start a Mandos client in the initial RAM

133

disk environment, the Mandos client program communicates with

134

this server program to get an encrypted password, which is then

135

decrypted and used to unlock the encrypted root file system.

136

The client host computer can then continue its boot sequence

137

normally.

137

138

</para>

138

139

140

</refsect1>

143

144

145

145

146

146

147

147

148

149

<para>

150

Show a help message and exit

153

</varlistentry>

154

155

156

157

158

<term><option>--interface</option>

159

156

<term><literal>-i</literal>, <literal>--interface <replaceable>

157

IF</replaceable></literal></term>

160

158

161

<xi:include href="mandos-options.xml" xpointer="interface"/>

159

<para>

160

Only announce the server and listen to requests on network

161

interface <replaceable>IF</replaceable>. Default is to

162

use all available interfaces.

163

</para>

162

164

</listitem>

163

165

</varlistentry>

164

166

168

<term><literal>-a</literal>, <literal>--address <replaceable>

167

169

ADDRESS</replaceable></literal></term>

168

170

169

<xi:include href="mandos-options.xml" xpointer="address"/>

171

<para>

172

If this option is used, the server will only listen to a

173

specific address. This must currently be an IPv6 address;

174

an IPv4 address can be specified using the

175

<quote><literal>::FFFF:192.0.2.3</literal></quote> syntax.

176

Also, if a link-local address is specified, an interface

177

should be set, since a link-local address is only valid on

178

a single interface. By default, the server will listen to

179

all available addresses.

180

</para>

170

181

</listitem>

171

182

</varlistentry>

172

183

174

185

175

186

PORT</replaceable></literal></term>

176

187

177

<xi:include href="mandos-options.xml" xpointer="port"/>

188

<para>

189

If this option is used, the server to bind to that

190

port. By default, the server will listen to an arbitrary

191

port given by the operating system.

192

</para>

178

193

</listitem>

179

194

</varlistentry>

180

195

182

197

<term><literal>--check</literal></term>

183

198

184

199

<para>

185

Run the server’s self-tests. This includes any unit

200

Run the server's self-tests. This includes any unit

186

201

tests, etc.

187

202

</para>

188

203

</listitem>

191

206

192

207

<term><literal>--debug</literal></term>

193

208

194

<xi:include href="mandos-options.xml" xpointer="debug"/>

209

<para>

210

If the server is run in debug mode, it will run in the

211

foreground and print a lot of debugging information. The

212

default is <emphasis>not</emphasis> to run in debug mode.

213

</para>

195

214

</listitem>

196

215

</varlistentry>

197

216

199

218

<term><literal>--priority <replaceable>

200

219

PRIORITY</replaceable></literal></term>

201

220

202

<xi:include href="mandos-options.xml" xpointer="priority"/>

221

<para>

222

GnuTLS priority string for the TLS handshake with the

223

clients. See

224

<citerefentry><refentrytitle>gnutls_priority_init

225

</refentrytitle><manvolnum>3</manvolnum></citerefentry>

226

for the syntax. The default is

227

<quote><literal>SECURE256:!CTYPE-X.509:+CTYPE-OPENPGP</literal></quote>.

228

<emphasis>Warning</emphasis>: changing this may make the

229

TLS handshake fail, making communication with clients

230

impossible.

231

</para>

203

232

</listitem>

204

233

</varlistentry>

205

234

207

236

<term><literal>--servicename <replaceable>NAME</replaceable>

208

237

</literal></term>

209

238

210

<xi:include href="mandos-options.xml"

211

xpointer="servicename"/>

239

<para>

240

Zeroconf service name. The default is

241

<quote><literal>Mandos</literal></quote>. You only need

242

to change this if you for some reason want to run more

243

than one server on the same <emphasis>host</emphasis>,

244

which would not normally be useful. If there are name

245

collisions on the same <emphasis>network</emphasis>, the

246

newer server will automatically rename itself to

247

<quote><literal>Mandos #2</literal></quote>, and so on,

248

therefore this option is not needed in that case.

249

</para>

212

250

</listitem>

213

251

</varlistentry>

214

252

238

276

</variablelist>

239

277

</refsect1>

240

278

241

242

<title>OVERVIEW</title>

243

<xi:include href="overview.xml"/>

244

<para>

245

This program is the server part. It is a normal server program

246

and will run in a normal system environment, not in an initial

247

RAM disk environment.

248

</para>

249

</refsect1>

250

251

279

252

280

<title>NETWORK PROTOCOL</title>

253

281

<para>

279

307

280

308

</row>

281

309

<row>

282

310

283

311

284

312

</row>

285

313

<row>

313

341

are still up. If a client has not been confirmed as being up

314

342

for some time, the client is assumed to be compromised and is no

315

343

longer eligible to receive the encrypted password. The timeout,

316

checker program, and interval between checks can be configured

344

checker program and interval between checks can be configured

317

345

both globally and per client; see <citerefentry>

346

<refentrytitle>mandos.conf</refentrytitle>

347

318

348

<refentrytitle>mandos-clients.conf</refentrytitle>

319

349

<manvolnum>5</manvolnum></citerefentry>.

320

350

</para>

323

353

324

354

<title>LOGGING</title>

325

355

<para>

326

The server will send log message with various severity levels to

327

<filename>/dev/log</filename>. With the

356

The server will send log messaged with various severity levels

357

to <filename>/dev/log</filename>. With the

328

358

<option>--debug</option> option, it will log even more messages,

329

359

and also show them on the console.

330

360

</para>

338

368

</para>

339

369

</refsect1>

340

370

341

342

<title>ENVIRONMENT</title>

343

344

345

346

347

<para>

348

To start the configured checker (see <xref

349

linkend="checking"/>), the server uses

350

<filename>/bin/sh</filename>, which in turn uses

351

<varname>PATH</varname> to search for matching commands if

352

an absolute path is not given. See <citerefentry>

353

354

</citerefentry>.

355

</para>

356

</listitem>

357

</varlistentry>

358

</variablelist>

359

</refsect1>

360

361

371

362

372

<title>FILES</title>

363

373

<para>

404

414

</para>

405

415

</listitem>

406

416

</varlistentry>

407

408

409

410

<para>

411

This is used to start the configured checker command for

412

each client. See <citerefentry>

413

<refentrytitle>mandos-clients.conf</refentrytitle>

414

<manvolnum>5</manvolnum></citerefentry> for details.

415

</para>

416

</listitem>

417

</varlistentry>

418

417

</variablelist>

419

418

</refsect1>

420

419

421

420

422

421

423

422

<para>

424

423

This server might, on especially fatal errors, emit a Python

425

424

backtrace. This could be considered a feature.

426

425

</para>

427

<para>

428

Currently, if a client is declared <quote>invalid</quote> due to

429

having timed out, the server does not record this fact onto

430

permanent storage. This has some security implications, see

431

<xref linkend="CLIENTS"/>.

432

</para>

433

<para>

434

There is currently no way of querying the server of the current

435

status of clients, other than analyzing its <systemitem

436

class="service">syslog</systemitem> output.

437

</para>

438

<para>

439

There is no fine-grained control over logging and debug output.

440

</para>

441

<para>

442

Debug mode is conflated with running in the foreground.

443

</para>

444

<para>

445

The console log messages does not show a timestamp.

446

</para>

447

426

</refsect1>

448

449

450

<title>EXAMPLE</title>

427

428

429

<title>EXAMPLES</title>

451

430

452

431

<para>

453

432

Normal invocation needs no options:

454

433

</para>

455

434

<para>

456

<userinput>&COMMANDNAME;</userinput>

435

<userinput>mandos</userinput>

457

436

</para>

458

437

</informalexample>

459

438

460

439

<para>

461

Run the server in debug mode, read configuration files from

462

the <filename>~/mandos</filename> directory, and use the

463

Zeroconf service name <quote>Test</quote> to not collide with

464

any other official Mandos server on this host:

440

Run the server in debug mode and read configuration files from

441

the <filename>~/mandos</filename> directory:

465

442

</para>

466

443

<para>

467

444

468

445

469

<userinput>&COMMANDNAME; --debug --configdir ~/mandos --servicename Test</userinput>

446

<userinput>mandos --debug --configdir ~/mandos --servicename Test</userinput>

470

447

471

448

</para>

472

449

</informalexample>

478

455

<para>

479

456

480

457

481

<userinput>&COMMANDNAME; --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>

458

<userinput>mandos --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>

482

459

483

460

</para>

484

461

</informalexample>

486

463

487

464

488

465

<title>SECURITY</title>

489

466

490

467

<title>SERVER</title>

491

468

<para>

492

Running this <command>&COMMANDNAME;</command> server program

493

should not in itself present any security risk to the host

494

computer running it. The program does not need any special

495

privileges to run, and is designed to run as a non-root user.

469

Running the server should not in itself present any security

470

risk to the host computer running it.

496

471

</para>

497

472

</refsect2>

498

473

499

474

<title>CLIENTS</title>

500

475

<para>

501

476

The server only gives out its stored data to clients which

506

481

itself and looks up the fingerprint in its list of

507

482

clients. The <filename>clients.conf</filename> file (see

508

483

<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>

509

<manvolnum>5</manvolnum></citerefentry>)

510

<emphasis>must</emphasis> be made non-readable by anyone

511

except the user running the server.

512

</para>

513

<para>

514

As detailed in <xref linkend="checking"/>, the status of all

515

client computers will continually be checked and be assumed

516

compromised if they are gone for too long.

517

</para>

518

<para>

519

If a client is compromised, its downtime should be duly noted

520

by the server which would therefore declare the client

521

invalid. But if the server was ever restarted, it would

522

re-read its client list from its configuration file and again

523

regard all clients therein as valid, and hence eligible to

524

receive their passwords. Therefore, be careful when

525

restarting servers if it is suspected that a client has, in

526

fact, been compromised by parties who may now be running a

527

fake Mandos client with the keys from the non-encrypted

528

initial RAM image of the client host. What should be done in

529

that case (if restarting the server program really is

530

necessary) is to stop the server program, edit the

531

configuration file to omit any suspect clients, and restart

532

the server program.

484

<manvolnum>5</manvolnum></citerefentry>) must be non-readable

485

by anyone except the user running the server.

533

486

</para>

534

487

<para>

535

488

For more details on client-side security, see

541

494

542

495

543

496

544

<para>

545

546

<refentrytitle>mandos-clients.conf</refentrytitle>

547

548

<refentrytitle>mandos.conf</refentrytitle>

549

550

<refentrytitle>password-request</refentrytitle>

551

<manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>

552

553

</citerefentry>

554

</para>

555

556

557

<term>

558

<ulink url="http://www.zeroconf.org/">Zeroconf</ulink>

559

</term>

560

561

<para>

562

Zeroconf is the network protocol standard used by clients

563

for finding this Mandos server on the local network.

564

</para>

565

</listitem>

566

</varlistentry>

567

568

<term>

569

<ulink url="http://www.avahi.org/">Avahi</ulink>

570

</term>

571

572

<para>

573

Avahi is the library this server calls to implement

574

Zeroconf service announcements.

575

</para>

576

</listitem>

577

</varlistentry>

578

579

<term>

580

<ulink url="http://www.gnu.org/software/gnutls/"

581

>GnuTLS</ulink>

582

</term>

583

584

<para>

585

GnuTLS is the library this server uses to implement TLS for

586

communicating securely with the client, and at the same time

587

confidently get the client’s public OpenPGP key.

588

</para>

589

</listitem>

590

</varlistentry>

591

592

<term>

593

RFC 4291: <citetitle>IP Version 6 Addressing

594

Architecture</citetitle>

595

</term>

596

597

598

599

<term>Section 2.2: <citetitle>Text Representation of

600

Addresses</citetitle></term>

601

602

</varlistentry>

603

604

<term>Section 2.5.5.2: <citetitle>IPv4-Mapped IPv6

605

Address</citetitle></term>

606

607

</varlistentry>

608

609

<term>Section 2.5.6, <citetitle>Link-Local IPv6 Unicast

610

Addresses</citetitle></term>

611

612

<para>

613

The clients use IPv6 link-local addresses, which are

614

immediately usable since a link-local addresses is

615

automatically assigned to a network interfaces when it

616

is brought up.

617

</para>

618

</listitem>

619

</varlistentry>

620

</variablelist>

621

</listitem>

622

</varlistentry>

623

624

<term>

625

RFC 4346: <citetitle>The Transport Layer Security (TLS)

626

Protocol Version 1.1</citetitle>

627

</term>

628

629

<para>

630

TLS 1.1 is the protocol implemented by GnuTLS.

631

</para>

632

</listitem>

633

</varlistentry>

634

635

<term>

636

RFC 4880: <citetitle>OpenPGP Message Format</citetitle>

637

</term>

638

639

<para>

640

The data sent to clients is binary encrypted OpenPGP data.

641

</para>

642

</listitem>

643

</varlistentry>

644

645

<term>

646

RFC 5081: <citetitle>Using OpenPGP Keys for Transport Layer

647

Security</citetitle>

648

</term>

649

650

<para>

651

This is implemented by GnuTLS and used by this server so

652

that OpenPGP keys can be used.

653

</para>

654

</listitem>

655

</varlistentry>

656

</variablelist>

497

498

499

<citerefentry><refentrytitle>password-request</refentrytitle>

500

<manvolnum>8mandos</manvolnum></citerefentry>

501

</para></listitem>

502

503

504

<citerefentry><refentrytitle>plugin-runner</refentrytitle>

505

<manvolnum>8mandos</manvolnum></citerefentry>

506

</para></listitem>

507

508

509

<ulink url="http://www.zeroconf.org/">Zeroconf</ulink>

510

</para></listitem>

511

512

513

<ulink url="http://www.avahi.org/">Avahi</ulink>

514

</para></listitem>

515

516

517

<ulink

518

url="http://www.gnu.org/software/gnutls/">GnuTLS</ulink>

519

</para></listitem>

520

521

522

<citation>RFC 4880: <citetitle>OpenPGP Message

523

Format</citetitle></citation>

524

</para></listitem>

525

526

527

<citation>RFC 5081: <citetitle>Using OpenPGP Keys for

528

Transport Layer Security</citetitle></citation>

529

</para></listitem>

530

531

532

<citation>RFC 4291: <citetitle>IP Version 6 Addressing

533

Architecture</citetitle>, section 2.5.6, Link-Local IPv6

534

Unicast Addresses</citation>

535

</para></listitem>

536

</itemizedlist>

657

537

</refsect1>

658

538

</refentry>

659

660

661

662

663