/mandos/release : revision 114

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"?>

1

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

4

2

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

5

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

3

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

6

4

<!ENTITY VERSION "1.0">

7

5

<!ENTITY COMMANDNAME "mandos">

6

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

8

7

]>

9

8

10

9

11

10

12

<title>&COMMANDNAME;</title>

13

14

<productname>&COMMANDNAME;</productname>

11

<title>Mandos Manual</title>

12

13

<productname>Mandos</productname>

15

14

<productnumber>&VERSION;</productnumber>

15

<date>&TIMESTAMP;</date>

16

17

18

<firstname>Björn</firstname>

74

75

76

<command>&COMMANDNAME;</command>

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>

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>

106

109

</cmdsynopsis>

107

110

</refsynopsisdiv>

108

111

112

115

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

113

116

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

114

117

client host computers. The Mandos server uses Zeroconf to

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.

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.

121

125

</para>

122

126

123

127

</refsect1>

127

131

128

132

<para>

129

133

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

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.

134

rebooting</emphasis> of client host computer with an

135

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

136

linkend="overview"/> for details.

138

137

</para>

139

138

140

139

</refsect1>

153

152

</varlistentry>

154

153

155

154

156

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

157

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

155

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

156

>NAME</replaceable></literal></term>

158

157

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>

158

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

164

159

</listitem>

165

160

</varlistentry>

166

161

168

163

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

169

164

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

170

165

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>

166

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

181

167

</listitem>

182

168

</varlistentry>

183

169

185

171

186

172

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

187

173

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>

174

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

193

175

</listitem>

194

176

</varlistentry>

195

177

197

179

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

198

180

199

181

<para>

200

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

182

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

201

183

tests, etc.

202

184

</para>

203

185

</listitem>

206

188

207

189

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

208

190

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>

191

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

214

192

</listitem>

215

193

</varlistentry>

216

194

218

196

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

219

197

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

220

198

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>

199

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

232

200

</listitem>

233

201

</varlistentry>

234

202

236

204

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

237

205

</literal></term>

238

206

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>

207

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

208

xpointer="servicename"/>

250

209

</listitem>

251

210

</varlistentry>

252

211

276

235

</variablelist>

277

236

</refsect1>

278

237

238

239

<title>OVERVIEW</title>

240

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

241

<para>

242

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

243

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

244

RAM disk environment.

245

</para>

246

</refsect1>

247

279

248

280

249

<title>NETWORK PROTOCOL</title>

281

250

<para>

307

276

308

277

</row>

309

278

<row>

310

279

311

280

312

281

</row>

313

282

<row>

341

310

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

342

311

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

343

312

longer eligible to receive the encrypted password. The timeout,

344

checker program and interval between checks can be configured

313

checker program, and interval between checks can be configured

345

314

both globally and per client; see <citerefentry>

346

<refentrytitle>mandos.conf</refentrytitle>

347

348

315

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

349

316

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

350

317

</para>

353

320

354

321

<title>LOGGING</title>

355

322

<para>

356

The server will send log messaged with various severity levels

357

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

323

The server will send log message with various severity levels to

324

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

358

325

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

359

326

and also show them on the console.

360

327

</para>

368

335

</para>

369

336

</refsect1>

370

337

338

339

<title>ENVIRONMENT</title>

340

341

342

343

344

<para>

345

To start the configured checker (see <xref

346

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

347

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

348

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

349

an absolute path is not given. See <citerefentry>

350

351

</citerefentry>.

352

</para>

353

</listitem>

354

</varlistentry>

355

</variablelist>

356

</refsect1>

357

371

358

372

359

<title>FILES</title>

373

360

<para>

414

401

</para>

415

402

</listitem>

416

403

</varlistentry>

404

405

406

407

<para>

408

This is used to start the configured checker command for

409

each client. See <citerefentry>

410

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

411

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

412

</para>

413

</listitem>

414

</varlistentry>

417

415

</variablelist>

418

416

</refsect1>

419

417

420

418

421

419

422

420

<para>

423

421

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

424

422

backtrace. This could be considered a feature.

425

423

</para>

424

<para>

425

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

426

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

427

permanent storage. This has some security implications, see

428

<xref linkend="CLIENTS"/>.

429

</para>

430

<para>

431

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

432

status of clients, other than analyzing its <systemitem

433

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

434

</para>

435

<para>

436

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

437

</para>

438

<para>

439

Debug mode is conflated with running in the foreground.

440

</para>

441

<para>

442

The console log messages does not show a timestamp.

443

</para>

426

444

</refsect1>

427

428

429

<title>EXAMPLES</title>

445

446

447

<title>EXAMPLE</title>

430

448

431

449

<para>

432

450

Normal invocation needs no options:

433

451

</para>

434

452

<para>

435

<userinput>mandos</userinput>

453

<userinput>&COMMANDNAME;</userinput>

436

454

</para>

437

455

</informalexample>

438

456

439

457

<para>

440

Run the server in debug mode and read configuration files from

441

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

458

Run the server in debug mode, read configuration files from

459

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

460

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

461

any other official Mandos server on this host:

442

462

</para>

443

463

<para>

444

464

445

465

446

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

466

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

447

467

448

468

</para>

449

469

</informalexample>

455

475

<para>

456

476

457

477

458

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

478

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

459

479

460

480

</para>

461

481

</informalexample>

463

483

464

484

465

485

<title>SECURITY</title>

466

486

467

487

<title>SERVER</title>

468

488

<para>

469

Running the server should not in itself present any security

470

risk to the host computer running it.

489

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

490

should not in itself present any security risk to the host

491

computer running it. The program does not need any special

492

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

471

493

</para>

472

494

</refsect2>

473

495

474

496

<title>CLIENTS</title>

475

497

<para>

476

498

The server only gives out its stored data to clients which

481

503

itself and looks up the fingerprint in its list of

482

504

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

483

505

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

484

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

485

by anyone except the user running the server.

506

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

507

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

508

except the user running the server.

509

</para>

510

<para>

511

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

512

client computers will continually be checked and be assumed

513

compromised if they are gone for too long.

514

</para>

515

<para>

516

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

517

by the server which would therefore declare the client

518

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

519

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

520

regard all clients therein as valid, and hence eligible to

521

receive their passwords. Therefore, be careful when

522

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

523

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

524

fake Mandos client with the keys from the non-encrypted

525

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

526

that case (if restarting the server program really is

527

necessary) is to stop the server program, edit the

528

configuration file to omit any suspect clients, and restart

529

the server program.

486

530

</para>

487

531

<para>

488

532

For more details on client-side security, see

494

538

495

539

496

540

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>

541

<para>

542

543

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

544

545

<refentrytitle>mandos.conf</refentrytitle>

546

547

<refentrytitle>password-request</refentrytitle>

548

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

549

550

</citerefentry>

551

</para>

552

553

554

<term>

555

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

556

</term>

557

558

<para>

559

Zeroconf is the network protocol standard used by clients

560

for finding this Mandos server on the local network.

561

</para>

562

</listitem>

563

</varlistentry>

564

565

<term>

566

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

567

</term>

568

569

<para>

570

Avahi is the library this server calls to implement

571

Zeroconf service announcements.

572

</para>

573

</listitem>

574

</varlistentry>

575

576

<term>

577

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

578

>GnuTLS</ulink>

579

</term>

580

581

<para>

582

GnuTLS is the library this server uses to implement TLS for

583

communicating securely with the client, and at the same time

584

confidently get the client’s public OpenPGP key.

585

</para>

586

</listitem>

587

</varlistentry>

588

589

<term>

590

RFC 4291: <citetitle>IP Version 6 Addressing

591

Architecture</citetitle>

592

</term>

593

594

595

596

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

597

Addresses</citetitle></term>

598

599

</varlistentry>

600

601

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

602

Address</citetitle></term>

603

604

</varlistentry>

605

606

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

607

Addresses</citetitle></term>

608

609

<para>

610

The clients use IPv6 link-local addresses, which are

611

immediately usable since a link-local addresses is

612

automatically assigned to a network interfaces when it

613

is brought up.

614

</para>

615

</listitem>

616

</varlistentry>

617

</variablelist>

618

</listitem>

619

</varlistentry>

620

621

<term>

622

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

623

Protocol Version 1.1</citetitle>

624

</term>

625

626

<para>

627

TLS 1.1 is the protocol implemented by GnuTLS.

628

</para>

629

</listitem>

630

</varlistentry>

631

632

<term>

633

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

634

</term>

635

636

<para>

637

The data sent to clients is binary encrypted OpenPGP data.

638

</para>

639

</listitem>

640

</varlistentry>

641

642

<term>

643

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

644

Security</citetitle>

645

</term>

646

647

<para>

648

This is implemented by GnuTLS and used by this server so

649

that OpenPGP keys can be used.

650

</para>

651

</listitem>

652

</varlistentry>

653

</variablelist>

537

654

</refsect1>

538

655

</refentry>

656

657

658

659

660