/mandos/trunk : revision 123

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

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>

67

68

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

69

70

Sends encrypted passwords to authenticated Mandos clients

70

Gives encrypted passwords to authenticated Mandos clients

71

</refpurpose>

72

</refnamediv>

73

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

<group>

78

<arg choice="plain"><option>--interface

79

80

<arg choice="plain"><option>-i

81

82

</group>

83

<sbr/>

84

<group>

85

<arg choice="plain"><option>--address

86

<replaceable>ADDRESS</replaceable></option></arg>

87

<arg choice="plain"><option>-a

88

<replaceable>ADDRESS</replaceable></option></arg>

89

</group>

90

<sbr/>

91

<group>

92

<arg choice="plain"><option>--port

93

94

<arg choice="plain"><option>-p

95

96

</group>

97

<sbr/>

98

<arg><option>--priority

99

<replaceable>PRIORITY</replaceable></option></arg>

100

<sbr/>

101

<arg><option>--servicename

102

103

<sbr/>

104

<arg><option>--configdir

105

<replaceable>DIRECTORY</replaceable></option></arg>

106

<sbr/>

107

<arg><option>--debug</option></arg>

108

</cmdsynopsis>

109

110

<command>&COMMANDNAME;</command>

111

112

113

114

</group>

115

</cmdsynopsis>

116

117

<command>&COMMANDNAME;</command>

118

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

119

</cmdsynopsis>

120

121

<command>&COMMANDNAME;</command>

122

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

106

123

</cmdsynopsis>

107

124

</refsynopsisdiv>

108

125

112

129

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

113

130

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

114

131

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.

132

announce itself on the local network, and uses TLS to

133

communicate securely with and to authenticate the clients. The

134

Mandos server uses IPv6 to allow Mandos clients to use IPv6

135

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

136

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

137

Any authenticated client is then given the stored pre-encrypted

138

password for that specific client.

121

139

</para>

122

140

123

141

</refsect1>

127

145

128

146

<para>

129

147

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.

148

rebooting</emphasis> of client host computer with an

149

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

150

linkend="overview"/> for details.

138

151

</para>

139

152

140

153

</refsect1>

144

157

145

158

146

159

147

160

161

148

162

149

163

<para>

150

164

Show a help message and exit

153

167

</varlistentry>

154

168

155

169

156

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

157

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

170

171

172

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

173

158

174

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>

175

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

164

176

</listitem>

165

177

</varlistentry>

166

178

168

180

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

169

181

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

170

182

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>

183

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

181

184

</listitem>

182

185

</varlistentry>

183

186

185

188

186

189

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

187

190

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>

191

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

193

192

</listitem>

194

193

</varlistentry>

195

194

197

196

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

198

197

199

198

<para>

200

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

199

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

201

200

tests, etc.

202

201

</para>

203

202

</listitem>

206

205

207

206

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

208

207

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>

208

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

214

209

</listitem>

215

210

</varlistentry>

216

211

218

213

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

219

214

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

220

215

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>

216

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

232

217

</listitem>

233

218

</varlistentry>

234

219

236

221

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

237

222

</literal></term>

238

223

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>

224

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

225

xpointer="servicename"/>

250

226

</listitem>

251

227

</varlistentry>

252

228

276

252

</variablelist>

277

253

</refsect1>

278

254

255

256

<title>OVERVIEW</title>

257

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

258

<para>

259

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

260

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

261

RAM disk environment.

262

</para>

263

</refsect1>

264

279

265

280

266

<title>NETWORK PROTOCOL</title>

281

267

<para>

307

293

308

294

</row>

309

295

<row>

310

296

311

297

312

298

</row>

313

299

<row>

341

327

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

342

328

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

343

329

longer eligible to receive the encrypted password. The timeout,

344

checker program and interval between checks can be configured

330

checker program, and interval between checks can be configured

345

331

both globally and per client; see <citerefentry>

346

<refentrytitle>mandos.conf</refentrytitle>

347

348

332

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

349

333

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

350

334

</para>

353

337

354

338

<title>LOGGING</title>

355

339

<para>

356

The server will send log messaged with various severity levels

357

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

340

The server will send log message with various severity levels to

341

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

358

342

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

359

343

and also show them on the console.

360

344

</para>

368

352

</para>

369

353

</refsect1>

370

354

355

356

<title>ENVIRONMENT</title>

357

358

359

360

361

<para>

362

To start the configured checker (see <xref

363

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

364

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

365

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

366

an absolute path is not given. See <citerefentry>

367

368

</citerefentry>.

369

</para>

370

</listitem>

371

</varlistentry>

372

</variablelist>

373

</refsect1>

374

371

375

372

376

<title>FILES</title>

373

377

<para>

414

418

</para>

415

419

</listitem>

416

420

</varlistentry>

421

422

423

424

<para>

425

This is used to start the configured checker command for

426

each client. See <citerefentry>

427

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

428

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

429

</para>

430

</listitem>

431

</varlistentry>

417

432

</variablelist>

418

433

</refsect1>

419

434

420

435

421

436

422

437

<para>

423

438

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

424

439

backtrace. This could be considered a feature.

425

440

</para>

441

<para>

442

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

443

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

444

permanent storage. This has some security implications, see

445

<xref linkend="CLIENTS"/>.

446

</para>

447

<para>

448

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

449

status of clients, other than analyzing its <systemitem

450

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

451

</para>

452

<para>

453

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

454

</para>

455

<para>

456

Debug mode is conflated with running in the foreground.

457

</para>

458

<para>

459

The console log messages does not show a timestamp.

460

</para>

426

461

</refsect1>

427

428

429

<title>EXAMPLES</title>

462

463

464

<title>EXAMPLE</title>

430

465

431

466

<para>

432

467

Normal invocation needs no options:

433

468

</para>

434

469

<para>

435

<userinput>mandos</userinput>

470

<userinput>&COMMANDNAME;</userinput>

436

471

</para>

437

472

</informalexample>

438

473

439

474

<para>

440

Run the server in debug mode and read configuration files from

441

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

475

Run the server in debug mode, read configuration files from

476

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

477

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

478

any other official Mandos server on this host:

442

479

</para>

443

480

<para>

444

481

445

482

446

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

483

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

447

484

448

485

</para>

449

486

</informalexample>

455

492

<para>

456

493

457

494

458

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

495

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

459

496

460

497

</para>

461

498

</informalexample>

463

500

464

501

465

502

<title>SECURITY</title>

466

503

467

504

<title>SERVER</title>

468

505

<para>

469

Running the server should not in itself present any security

470

risk to the host computer running it.

506

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

507

should not in itself present any security risk to the host

508

computer running it. The program does not need any special

509

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

471

510

</para>

472

511

</refsect2>

473

512

474

513

<title>CLIENTS</title>

475

514

<para>

476

515

The server only gives out its stored data to clients which

481

520

itself and looks up the fingerprint in its list of

482

521

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

483

522

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

484

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

485

by anyone except the user running the server.

523

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

524

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

525

except the user running the server.

526

</para>

527

<para>

528

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

529

client computers will continually be checked and be assumed

530

compromised if they are gone for too long.

531

</para>

532

<para>

533

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

534

by the server which would therefore declare the client

535

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

536

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

537

regard all clients therein as valid, and hence eligible to

538

receive their passwords. Therefore, be careful when

539

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

540

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

541

fake Mandos client with the keys from the non-encrypted

542

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

543

that case (if restarting the server program really is

544

necessary) is to stop the server program, edit the

545

configuration file to omit any suspect clients, and restart

546

the server program.

486

547

</para>

487

548

<para>

488

549

For more details on client-side security, see

494

555

495

556

496

557

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>

558

<para>

559

560

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

561

562

<refentrytitle>mandos.conf</refentrytitle>

563

564

<refentrytitle>password-request</refentrytitle>

565

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

566

567

</citerefentry>

568

</para>

569

570

571

<term>

572

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

573

</term>

574

575

<para>

576

Zeroconf is the network protocol standard used by clients

577

for finding this Mandos server on the local network.

578

</para>

579

</listitem>

580

</varlistentry>

581

582

<term>

583

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

584

</term>

585

586

<para>

587

Avahi is the library this server calls to implement

588

Zeroconf service announcements.

589

</para>

590

</listitem>

591

</varlistentry>

592

593

<term>

594

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

595

>GnuTLS</ulink>

596

</term>

597

598

<para>

599

GnuTLS is the library this server uses to implement TLS for

600

communicating securely with the client, and at the same time

601

confidently get the client’s public OpenPGP key.

602

</para>

603

</listitem>

604

</varlistentry>

605

606

<term>

607

RFC 4291: <citetitle>IP Version 6 Addressing

608

Architecture</citetitle>

609

</term>

610

611

612

613

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

614

Addresses</citetitle></term>

615

616

</varlistentry>

617

618

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

619

Address</citetitle></term>

620

621

</varlistentry>

622

623

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

624

Addresses</citetitle></term>

625

626

<para>

627

The clients use IPv6 link-local addresses, which are

628

immediately usable since a link-local addresses is

629

automatically assigned to a network interfaces when it

630

is brought up.

631

</para>

632

</listitem>

633

</varlistentry>

634

</variablelist>

635

</listitem>

636

</varlistentry>

637

638

<term>

639

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

640

Protocol Version 1.1</citetitle>

641

</term>

642

643

<para>

644

TLS 1.1 is the protocol implemented by GnuTLS.

645

</para>

646

</listitem>

647

</varlistentry>

648

649

<term>

650

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

651

</term>

652

653

<para>

654

The data sent to clients is binary encrypted OpenPGP data.

655

</para>

656

</listitem>

657

</varlistentry>

658

659

<term>

660

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

661

Security</citetitle>

662

</term>

663

664

<para>

665

This is implemented by GnuTLS and used by this server so

666

that OpenPGP keys can be used.

667

</para>

668

</listitem>

669

</varlistentry>

670

</variablelist>

537

671

</refsect1>

538

672

</refentry>

673

674

675

676

677