/mandos/trunk : revision 86

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 OVERVIEW SYSTEM "overview.xml">

8

7

]>

9

8

10

9

11

10

12

11

<title>&COMMANDNAME;</title>

13

12

14

13

<productname>&COMMANDNAME;</productname>

15

14

<productnumber>&VERSION;</productnumber>

16

15

74

73

75

74

76

75

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

76

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

77

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

78

79

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

80

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

81

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

82

<arg>--debug</arg>

83

</cmdsynopsis>

84

85

<command>&COMMANDNAME;</command>

86

87

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

88

89

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

90

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

91

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

92

<arg>--debug</arg>

93

</cmdsynopsis>

94

95

<command>&COMMANDNAME;</command>

96

97

98

99

</group>

100

</cmdsynopsis>

101

102

<command>&COMMANDNAME;</command>

103

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

104

</cmdsynopsis>

105

106

<command>&COMMANDNAME;</command>

107

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

106

108

</cmdsynopsis>

107

109

</refsynopsisdiv>

108

110

112

114

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

113

115

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

114

116

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.

117

announce itself on the local network, and uses TLS to

118

communicate securely with and to authenticate the clients. The

119

Mandos server uses IPv6 to allow Mandos clients to use IPv6

120

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

121

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

122

Any authenticated client is then given the stored pre-encrypted

123

password for that specific client.

121

124

</para>

122

125

123

126

</refsect1>

127

130

128

131

<para>

129

132

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.

133

rebooting</emphasis> of client host computer with an

134

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

135

linkend="overview"/> for details.

138

136

</para>

139

137

140

138

</refsect1>

159

157

<para>

160

158

Only announce the server and listen to requests on network

161

159

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

162

use all available interfaces.

160

use all available interfaces. <emphasis>Note:</emphasis>

161

a failure to bind to the specified interface is not

162

considered critical, and the server does not exit.

163

</para>

164

</listitem>

165

</varlistentry>

197

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

198

199

<para>

200

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

200

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

201

tests, etc.

202

</para>

203

</listitem>

220

221

<para>

222

GnuTLS priority string for the TLS handshake with the

223

clients. See

224

<citerefentry><refentrytitle>gnutls_priority_init

223

clients. The default is

224

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

225

See <citerefentry><refentrytitle>gnutls_priority_init

225

226

</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.

227

for the syntax. <emphasis>Warning</emphasis>: changing

228

this may make the TLS handshake fail, making communication

229

with clients impossible.

231

230

</para>

232

231

</listitem>

233

232

</varlistentry>

238

237

239

238

<para>

240

239

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.

240

<quote><literal>Mandos</literal></quote>. This only needs

241

to be changed this if it, for some reason, is necessary to

242

run more than one server on the same

243

<emphasis>host</emphasis>, which would not normally be

244

useful. If there are name collisions on the same

245

<emphasis>network</emphasis>, the newer server will

246

automatically rename itself to <quote><literal>Mandos

247

#2</literal></quote>, and so on; therefore, this option is

248

not needed in that case.

249

</para>

250

</listitem>

251

</varlistentry>

276

</variablelist>

277

</refsect1>

278

279

280

<title>OVERVIEW</title>

281

&OVERVIEW;

282

<para>

283

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

284

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

285

RAM disk environment.

286

</para>

287

</refsect1>

288

279

289

280

290

<title>NETWORK PROTOCOL</title>

281

291

<para>

341

351

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

342

352

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

343

353

longer eligible to receive the encrypted password. The timeout,

344

checker program and interval between checks can be configured

354

checker program, and interval between checks can be configured

345

355

both globally and per client; see <citerefentry>

346

356

<refentrytitle>mandos.conf</refentrytitle>

347

357

368

378

</para>

369

379

</refsect1>

370

380

381

382

<title>ENVIRONMENT</title>

383

384

385

386

387

<para>

388

To start the configured checker (see <xref

389

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

390

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

391

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

392

an absolute path is not given. See <citerefentry>

393

394

</citerefentry>

395

</para>

396

</listitem>

397

</varlistentry>

398

</variablelist>

399

</refsect1>

400

371

401

372

402

<title>FILES</title>

373

403

<para>

414

444

</para>

415

445

</listitem>

416

446

</varlistentry>

447

448

449

450

<para>

451

This is used to start the configured checker command for

452

each client. See <citerefentry>

453

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

454

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

455

</para>

456

</listitem>

457

</varlistentry>

417

458

</variablelist>

418

459

</refsect1>

419

460

420

461

421

462

422

463

<para>

423

464

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

424

465

backtrace. This could be considered a feature.

425

466

</para>

467

<para>

468

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

469

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

470

permanent storage. This has some security implications, see

471

<xref linkend="CLIENTS"/>.

472

</para>

473

<para>

474

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

475

status of clients, other than analyzing its <systemitem

476

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

477

</para>

478

<para>

479

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

480

</para>

481

<para>

482

Debug mode is conflated with running in the foreground.

483

</para>

484

<para>

485

The console log messages does not show a timestamp.

486

</para>

426

487

</refsect1>

427

428

429

<title>EXAMPLES</title>

488

489

490

<title>EXAMPLE</title>

430

491

431

492

<para>

432

493

Normal invocation needs no options:

437

498

</informalexample>

438

499

439

500

<para>

440

Run the server in debug mode and read configuration files from

441

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

501

Run the server in debug mode, read configuration files from

502

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

503

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

504

any other official Mandos server on this host:

442

505

</para>

443

506

<para>

444

507

463

526

464

527

465

528

<title>SECURITY</title>

466

529

467

530

<title>SERVER</title>

468

531

<para>

469

Running the server should not in itself present any security

470

risk to the host computer running it.

532

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

533

should not in itself present any security risk to the host

534

computer running it. The program does not need any special

535

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

471

536

</para>

472

537

</refsect2>

473

538

474

539

<title>CLIENTS</title>

475

540

<para>

476

541

The server only gives out its stored data to clients which

481

546

itself and looks up the fingerprint in its list of

482

547

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

483

548

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

484

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

485

by anyone except the user running the server.

549

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

550

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

551

except the user running the server.

552

</para>

553

<para>

554

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

555

client computers will continually be checked and be assumed

556

compromised if they are gone for too long.

557

</para>

558

<para>

559

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

560

by the server which would therefore declare the client

561

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

562

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

563

regard all clients therein as valid, and hence eligible to

564

receive their passwords. Therefore, be careful when

565

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

566

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

567

fake Mandos client with the keys from the non-encrypted

568

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

569

that case (if restarting the server program really is

570

necessary) is to stop the server program, edit the

571

configuration file to omit any suspect clients, and restart

572

the server program.

486

573

</para>

487

574

<para>

488

575

For more details on client-side security, see

494

581

495

582

496

583

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>

584

585

586

<term>

587

588

<refentrytitle>password-request</refentrytitle>

589

<manvolnum>8mandos</manvolnum>

590

</citerefentry>

591

</term>

592

593

<para>

594

This is the actual program which talks to this server.

595

Note that it is normally not invoked directly, and is only

596

run in the initial RAM disk environment, and not on a

597

fully started system.

598

</para>

599

</listitem>

600

</varlistentry>

601

602

<term>

603

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

604

</term>

605

606

<para>

607

Zeroconf is the network protocol standard used by clients

608

for finding this Mandos server on the local network.

609

</para>

610

</listitem>

611

</varlistentry>

612

613

<term>

614

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

615

</term>

616

617

<para>

618

Avahi is the library this server calls to implement

619

Zeroconf service announcements.

620

</para>

621

</listitem>

622

</varlistentry>

623

624

<term>

625

<ulink

626

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

627

</term>

628

629

<para>

630

GnuTLS is the library this server uses to implement TLS for

631

communicating securely with the client, and at the same time

632

confidently get the client’s public OpenPGP key.

633

</para>

634

</listitem>

635

</varlistentry>

636

637

<term>

638

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

639

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

640

Unicast Addresses</citation>

641

</term>

642

643

<para>

644

The clients use IPv6 link-local addresses, which are

645

immediately usable since a link-local addresses is

646

automatically assigned to a network interfaces when it is

647

brought up.

648

</para>

649

</listitem>

650

</varlistentry>

651

652

<term>

653

<citation>RFC 4346: <citetitle>The Transport Layer Security

654

(TLS) Protocol Version 1.1</citetitle></citation>

655

</term>

656

657

<para>

658

TLS 1.1 is the protocol implemented by GnuTLS.

659

</para>

660

</listitem>

661

</varlistentry>

662

663

<term>

664

<citation>RFC 4880: <citetitle>OpenPGP Message

665

Format</citetitle></citation>

666

</term>

667

668

<para>

669

The data sent to clients is binary encrypted OpenPGP data.

670

</para>

671

</listitem>

672

</varlistentry>

673

674

<term>

675

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

676

Transport Layer Security</citetitle></citation>

677

</term>

678

679

<para>

680

This is implemented by GnuTLS and used by this server so

681

that OpenPGP keys can be used.

682

</para>

683

</listitem>

684

</varlistentry>

685

</variablelist>

537

686

</refsect1>

538

687

</refentry>