/mandos/release : revision 24.1.64

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

8

6

]>

9

7

10

8

11

9

12

10

<title>&COMMANDNAME;</title>

13

11

14

12

<productname>&COMMANDNAME;</productname>

15

13

<productnumber>&VERSION;</productnumber>

16

14

74

72

75

73

76

74

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

75

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

76

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

77

78

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

79

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

80

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

81

<arg>--debug</arg>

82

</cmdsynopsis>

83

84

<command>&COMMANDNAME;</command>

85

86

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

87

88

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

89

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

90

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

91

<arg>--debug</arg>

92

</cmdsynopsis>

93

94

<command>&COMMANDNAME;</command>

95

96

97

98

</group>

99

</cmdsynopsis>

100

101

<command>&COMMANDNAME;</command>

102

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

103

</cmdsynopsis>

104

105

<command>&COMMANDNAME;</command>

106

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

106

107

</cmdsynopsis>

107

108

</refsynopsisdiv>

108

109

112

113

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

113

114

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

114

115

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.

116

announce itself on the local network, and uses TLS to

117

communicate securely with and to authenticate the clients. The

118

Mandos server uses IPv6 to allow Mandos clients to use IPv6

119

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

120

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

121

Any authenticated client is then given the stored pre-encrypted

122

password for that specific client.

121

123

</para>

122

124

123

125

</refsect1>

127

129

128

130

<para>

129

131

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.

132

rebooting</emphasis> of client host computer with an

133

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

134

linkend="overview"/> for details.

138

135

</para>

139

136

140

137

</refsect1>

156

153

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

157

154

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

158

155

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>

156

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

164

157

</listitem>

165

158

</varlistentry>

166

159

168

161

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

169

162

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

170

163

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>

164

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

181

165

</listitem>

182

166

</varlistentry>

183

167

185

169

186

170

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

187

171

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>

172

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

193

173

</listitem>

194

174

</varlistentry>

195

175

197

177

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

198

178

199

179

<para>

200

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

180

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

201

181

tests, etc.

202

182

</para>

203

183

</listitem>

206

186

207

187

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

208

188

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>

189

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

214

190

</listitem>

215

191

</varlistentry>

216

192

218

194

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

219

195

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

220

196

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>

197

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

232

198

</listitem>

233

199

</varlistentry>

234

200

236

202

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

237

203

</literal></term>

238

204

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>

205

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

206

xpointer="servicename"/>

250

207

</listitem>

251

208

</varlistentry>

252

209

276

233

</variablelist>

277

234

</refsect1>

278

235

236

237

<title>OVERVIEW</title>

238

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

239

<para>

240

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

241

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

242

RAM disk environment.

243

</para>

244

</refsect1>

245

279

246

280

247

<title>NETWORK PROTOCOL</title>

281

248

<para>

307

274

308

275

</row>

309

276

<row>

310

277

311

278

312

279

</row>

313

280

<row>

341

308

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

342

309

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

343

310

longer eligible to receive the encrypted password. The timeout,

344

checker program and interval between checks can be configured

311

checker program, and interval between checks can be configured

345

312

both globally and per client; see <citerefentry>

346

<refentrytitle>mandos.conf</refentrytitle>

347

348

313

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

349

314

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

350

315

</para>

353

318

354

319

<title>LOGGING</title>

355

320

<para>

356

The server will send log messaged with various severity levels

357

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

321

The server will send log message with various severity levels to

322

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

358

323

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

359

324

and also show them on the console.

360

325

</para>

368

333

</para>

369

334

</refsect1>

370

335

336

337

<title>ENVIRONMENT</title>

338

339

340

341

342

<para>

343

To start the configured checker (see <xref

344

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

345

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

346

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

347

an absolute path is not given. See <citerefentry>

348

349

</citerefentry>.

350

</para>

351

</listitem>

352

</varlistentry>

353

</variablelist>

354

</refsect1>

355

371

356

372

357

<title>FILES</title>

373

358

<para>

414

399

</para>

415

400

</listitem>

416

401

</varlistentry>

402

403

404

405

<para>

406

This is used to start the configured checker command for

407

each client. See <citerefentry>

408

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

409

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

410

</para>

411

</listitem>

412

</varlistentry>

417

413

</variablelist>

418

414

</refsect1>

419

415

420

416

421

417

422

418

<para>

423

419

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

424

420

backtrace. This could be considered a feature.

425

421

</para>

422

<para>

423

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

424

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

425

permanent storage. This has some security implications, see

426

<xref linkend="CLIENTS"/>.

427

</para>

428

<para>

429

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

430

status of clients, other than analyzing its <systemitem

431

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

432

</para>

433

<para>

434

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

435

</para>

436

<para>

437

Debug mode is conflated with running in the foreground.

438

</para>

439

<para>

440

The console log messages does not show a timestamp.

441

</para>

426

442

</refsect1>

427

428

429

<title>EXAMPLES</title>

443

444

445

<title>EXAMPLE</title>

430

446

431

447

<para>

432

448

Normal invocation needs no options:

437

453

</informalexample>

438

454

439

455

<para>

440

Run the server in debug mode and read configuration files from

441

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

456

Run the server in debug mode, read configuration files from

457

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

458

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

459

any other official Mandos server on this host:

442

460

</para>

443

461

<para>

444

462

463

481

464

482

465

483

<title>SECURITY</title>

466

484

467

485

<title>SERVER</title>

468

486

<para>

469

Running the server should not in itself present any security

470

risk to the host computer running it.

487

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

488

should not in itself present any security risk to the host

489

computer running it. The program does not need any special

490

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

471

491

</para>

472

492

</refsect2>

473

493

474

494

<title>CLIENTS</title>

475

495

<para>

476

496

The server only gives out its stored data to clients which

481

501

itself and looks up the fingerprint in its list of

482

502

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

483

503

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

484

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

485

by anyone except the user running the server.

504

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

505

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

506

except the user running the server.

507

</para>

508

<para>

509

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

510

client computers will continually be checked and be assumed

511

compromised if they are gone for too long.

512

</para>

513

<para>

514

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

515

by the server which would therefore declare the client

516

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

517

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

518

regard all clients therein as valid, and hence eligible to

519

receive their passwords. Therefore, be careful when

520

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

521

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

522

fake Mandos client with the keys from the non-encrypted

523

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

524

that case (if restarting the server program really is

525

necessary) is to stop the server program, edit the

526

configuration file to omit any suspect clients, and restart

527

the server program.

486

528

</para>

487

529

<para>

488

530

For more details on client-side security, see

494

536

495

537

496

538

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>

539

<para>

540

541

<refentrytitle>mandos.conf</refentrytitle>

542

543

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

544

545

<refentrytitle>password-request</refentrytitle>

546

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

547

548

</citerefentry>

549

</para>

550

551

552

<term>

553

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

554

</term>

555

556

<para>

557

Zeroconf is the network protocol standard used by clients

558

for finding this Mandos server on the local network.

559

</para>

560

</listitem>

561

</varlistentry>

562

563

<term>

564

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

565

</term>

566

567

<para>

568

Avahi is the library this server calls to implement

569

Zeroconf service announcements.

570

</para>

571

</listitem>

572

</varlistentry>

573

574

<term>

575

<ulink

576

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

577

</term>

578

579

<para>

580

GnuTLS is the library this server uses to implement TLS for

581

communicating securely with the client, and at the same time

582

confidently get the client’s public OpenPGP key.

583

</para>

584

</listitem>

585

</varlistentry>

586

587

<term>

588

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

589

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

590

Unicast Addresses</citation>

591

</term>

592

593

<para>

594

The clients use IPv6 link-local addresses, which are

595

immediately usable since a link-local addresses is

596

automatically assigned to a network interfaces when it is

597

brought up.

598

</para>

599

</listitem>

600

</varlistentry>

601

602

<term>

603

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

604

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

605

</term>

606

607

<para>

608

TLS 1.1 is the protocol implemented by GnuTLS.

609

</para>

610

</listitem>

611

</varlistentry>

612

613

<term>

614

<citation>RFC 4880: <citetitle>OpenPGP Message

615

Format</citetitle></citation>

616

</term>

617

618

<para>

619

The data sent to clients is binary encrypted OpenPGP data.

620

</para>

621

</listitem>

622

</varlistentry>

623

624

<term>

625

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

626

Transport Layer Security</citetitle></citation>

627

</term>

628

629

<para>

630

This is implemented by GnuTLS and used by this server so

631

that OpenPGP keys can be used.

632

</para>

633

</listitem>

634

</varlistentry>

635

</variablelist>

537

636

</refsect1>

538

637

</refentry>