/mandos/trunk : revision 173

3

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

4

<!ENTITY VERSION "1.0">

5

<!ENTITY COMMANDNAME "mandos">

6

<!ENTITY OVERVIEW SYSTEM "overview.xml">

6

<!ENTITY TIMESTAMP "2008-09-06">

7

]>

8

9

9

10

11

<title>&COMMANDNAME;</title>

11

<title>Mandos Manual</title>

12

13

<productname>&COMMANDNAME;</productname>

13

<productname>Mandos</productname>

14

<productnumber>&VERSION;</productnumber>

15

<date>&TIMESTAMP;</date>

15

16

16

17

17

18

<firstname>Björn</firstname>

33

34

<holder>Teddy Hogeborn</holder>

34

35

<holder>Björn Påhlsson</holder>

35

36

</copyright>

36

37

<para>

38

This manual page is free software: you can redistribute it

39

and/or modify it under the terms of the GNU General Public

40

License as published by the Free Software Foundation,

41

either version 3 of the License, or (at your option) any

42

later version.

43

</para>

44

45

<para>

46

This manual page is distributed in the hope that it will

47

be useful, but WITHOUT ANY WARRANTY; without even the

48

implied warranty of MERCHANTABILITY or FITNESS FOR A

49

PARTICULAR PURPOSE. See the GNU General Public License

50

for more details.

51

</para>

52

53

<para>

54

You should have received a copy of the GNU General Public

55

License along with this program; If not, see

56

<ulink url="http://www.gnu.org/licenses/"/>.

57

</para>

58

</legalnotice>

37

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

59

38

</refentryinfo>

60

39

61

40

66

45

67

46

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

68

47

69

Sends encrypted passwords to authenticated Mandos clients

48

Gives encrypted passwords to authenticated Mandos clients

70

49

</refpurpose>

71

50

</refnamediv>

72

51

73

52

74

53

75

54

<command>&COMMANDNAME;</command>

76

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

77

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

78

79

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

80

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

81

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

82

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

83

</cmdsynopsis>

84

85

<command>&COMMANDNAME;</command>

86

87

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

88

89

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

90

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

91

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

92

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

93

</cmdsynopsis>

94

95

<command>&COMMANDNAME;</command>

96

97

</cmdsynopsis>

98

99

<command>&COMMANDNAME;</command>

100

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

101

</cmdsynopsis>

102

103

<command>&COMMANDNAME;</command>

104

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

55

<group>

56

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

57

58

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

59

60

</group>

61

<sbr/>

62

<group>

63

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

64

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

65

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

66

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

67

</group>

68

<sbr/>

69

<group>

70

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

71

72

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

73

74

</group>

75

<sbr/>

76

<arg><option>--priority

77

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

78

<sbr/>

79

<arg><option>--servicename

80

81

<sbr/>

82

<arg><option>--configdir

83

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

84

<sbr/>

85

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

86

</cmdsynopsis>

87

88

<command>&COMMANDNAME;</command>

89

90

91

92

</group>

93

</cmdsynopsis>

94

95

<command>&COMMANDNAME;</command>

96

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

97

</cmdsynopsis>

98

99

<command>&COMMANDNAME;</command>

100

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

105

101

</cmdsynopsis>

106

102

</refsynopsisdiv>

107

103

119

115

Any authenticated client is then given the stored pre-encrypted

120

116

password for that specific client.

121

117

</para>

122

123

118

</refsect1>

124

119

125

120

126

121

<title>PURPOSE</title>

127

128

122

<para>

129

123

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

130

124

rebooting</emphasis> of client host computer with an

131

125

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

132

126

linkend="overview"/> for details.

133

127

</para>

134

135

128

</refsect1>

136

129

137

130

138

131

<title>OPTIONS</title>

139

140

132

141

133

142

134

135

143

136

144

137

<para>

145

138

Show a help message and exit

146

139

</para>

147

140

</listitem>

148

141

</varlistentry>

149

150

151

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

152

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

153

154

<para>

155

Only announce the server and listen to requests on network

156

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

157

use all available interfaces.

158

</para>

159

</listitem>

160

</varlistentry>

161

162

163

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

164

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

165

166

<para>

167

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

168

specific address. This must currently be an IPv6 address;

169

an IPv4 address can be specified using the

170

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

171

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

172

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

173

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

174

all available addresses.

175

</para>

176

</listitem>

177

</varlistentry>

178

179

180

181

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

182

183

<para>

184

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

185

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

186

port given by the operating system.

187

</para>

188

</listitem>

189

</varlistentry>

190

191

192

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

142

143

144

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

145

146

147

148

149

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

150

</listitem>

151

</varlistentry>

152

153

154

<term><option>--address

155

<replaceable>ADDRESS</replaceable></option></term>

156

<term><option>-a

157

<replaceable>ADDRESS</replaceable></option></term>

158

159

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

160

</listitem>

161

</varlistentry>

162

163

164

<term><option>--port

165

166

<term><option>-p

167

168

169

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

170

</listitem>

171

</varlistentry>

172

173

174

<term><option>--check</option></term>

193

175

194

176

<para>

195

177

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

197

179

</para>

198

180

</listitem>

199

181

</varlistentry>

200

201

202

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

203

204

<para>

205

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

206

foreground and print a lot of debugging information. The

207

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

208

</para>

209

</listitem>

210

</varlistentry>

211

212

213

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

214

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

215

216

<para>

217

GnuTLS priority string for the TLS handshake with the

218

clients. The default is

219

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

220

See <citerefentry><refentrytitle>gnutls_priority_init

221

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

222

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

223

this may make the TLS handshake fail, making communication

224

with clients impossible.

225

</para>

226

</listitem>

227

</varlistentry>

228

229

230

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

231

</literal></term>

232

233

<para>

234

Zeroconf service name. The default is

235

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

236

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

237

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

238

which would not normally be useful. If there are name

239

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

240

newer server will automatically rename itself to

241

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

242

therefore, this option is not needed in that case.

243

</para>

244

</listitem>

245

</varlistentry>

246

247

248

<term><literal>--configdir <replaceable>DIR</replaceable>

249

</literal></term>

182

183

184

<term><option>--debug</option></term>

185

186

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

187

</listitem>

188

</varlistentry>

189

190

191

<term><option>--priority <replaceable>

192

PRIORITY</replaceable></option></term>

193

194

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

195

</listitem>

196

</varlistentry>

197

198

199

<term><option>--servicename

200

201

202

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

203

xpointer="servicename"/>

204

</listitem>

205

</varlistentry>

206

207

208

<term><option>--configdir

209

<replaceable>DIRECTORY</replaceable></option></term>

250

210

251

211

<para>

252

212

Directory to search for configuration files. Default is

260

220

</varlistentry>

261

221

262

222

263

<term><literal>--version</literal></term>

223

<term><option>--version</option></term>

264

224

265

225

<para>

266

226

Prints the program version and exit.

272

232

273

233

274

234

<title>OVERVIEW</title>

275

&OVERVIEW;

235

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

276

236

<para>

277

237

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

278

238

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

279

RAM disk environment.

239

<acronym>RAM</acronym> disk environment.

280

240

</para>

281

241

</refsect1>

282

242

311

271

312

272

</row>

313

273

<row>

314

274

315

275

316

276

</row>

317

277

<row>

347

307

longer eligible to receive the encrypted password. The timeout,

348

308

checker program, and interval between checks can be configured

349

309

both globally and per client; see <citerefentry>

350

<refentrytitle>mandos.conf</refentrytitle>

351

352

310

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

353

311

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

354

312

</para>

357

315

358

316

<title>LOGGING</title>

359

317

<para>

360

The server will send log messaged with various severity levels

361

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

318

The server will send log message with various severity levels to

319

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

362

320

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

363

321

and also show them on the console.

364

322

</para>

372

330

</para>

373

331

</refsect1>

374

332

333

334

<title>ENVIRONMENT</title>

335

336

337

338

339

<para>

340

To start the configured checker (see <xref

341

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

342

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

343

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

344

an absolute path is not given. See <citerefentry>

345

346

</citerefentry>.

347

</para>

348

</listitem>

349

</varlistentry>

350

</variablelist>

351

</refsect1>

352

375

353

376

354

<title>FILES</title>

377

355

<para>

401

379

</listitem>

402

380

</varlistentry>

403

381

404

<term><filename>/var/run/mandos/mandos.pid</filename></term>

382

<term><filename>/var/run/mandos.pid</filename></term>

405

383

406

384

<para>

407

385

The file containing the process id of

418

396

</para>

419

397

</listitem>

420

398

</varlistentry>

399

400

401

402

<para>

403

This is used to start the configured checker command for

404

each client. See <citerefentry>

405

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

406

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

407

</para>

408

</listitem>

409

</varlistentry>

421

410

</variablelist>

422

411

</refsect1>

423

412

424

413

425

414

426

415

<para>

427

416

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

428

417

backtrace. This could be considered a feature.

429

418

</para>

419

<para>

420

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

421

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

422

permanent storage. This has some security implications, see

423

<xref linkend="CLIENTS"/>.

424

</para>

425

<para>

426

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

427

status of clients, other than analyzing its <systemitem

428

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

429

</para>

430

<para>

431

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

432

</para>

433

<para>

434

Debug mode is conflated with running in the foreground.

435

</para>

436

<para>

437

The console log messages does not show a time stamp.

438

</para>

439

<para>

440

This server does not check the expire time of clients’ OpenPGP

441

keys.

442

</para>

430

443

</refsect1>

431

432

433

<title>EXAMPLES</title>

444

445

446

<title>EXAMPLE</title>

434

447

435

448

<para>

436

449

Normal invocation needs no options:

437

450

</para>

438

451

<para>

439

<userinput>mandos</userinput>

452

<userinput>&COMMANDNAME;</userinput>

440

453

</para>

441

454

</informalexample>

442

455

449

462

<para>

450

463

451

464

452

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

465

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

453

466

454

467

</para>

455

468

</informalexample>

461

474

<para>

462

475

463

476

464

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

477

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

465

478

466

479

</para>

467

480

</informalexample>

469

482

470

483

471

484

<title>SECURITY</title>

472

485

473

486

<title>SERVER</title>

474

487

<para>

475

Running this &COMMANDNAME; server program should not in itself

476

present any security risk to the host computer running it.

477

The program does not need any special privileges to run, and

478

is designed to run as a non-root user.

488

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

489

should not in itself present any security risk to the host

490

computer running it. The program switches to a non-root user

491

soon after startup.

479

492

</para>

480

493

</refsect2>

481

494

482

495

<title>CLIENTS</title>

483

496

<para>

484

497

The server only gives out its stored data to clients which

499

512

compromised if they are gone for too long.

500

513

</para>

501

514

<para>

515

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

516

by the server which would therefore declare the client

517

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

518

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

519

regard all clients therein as valid, and hence eligible to

520

receive their passwords. Therefore, be careful when

521

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

522

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

523

fake Mandos client with the keys from the non-encrypted

524

initial <acronym>RAM</acronym> image of the client host. What

525

should be done in that case (if restarting the server program

526

really is necessary) is to stop the server program, edit the

527

configuration file to omit any suspect clients, and restart

528

the server program.

529

</para>

530

<para>

502

531

For more details on client-side security, see

503

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

532

<citerefentry><refentrytitle>mandos-client</refentrytitle>

504

533

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

505

534

</para>

506

535

</refsect2>

508

537

509

538

510

539

540

<para>

541

542

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

543

544

<refentrytitle>mandos.conf</refentrytitle>

545

546

<refentrytitle>mandos-client</refentrytitle>

547

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

548

549

</citerefentry>

550

</para>

511

551

512

552

513

553

<term>

514

515

<refentrytitle>password-request</refentrytitle>

516

<manvolnum>8mandos</manvolnum>

517

</citerefentry>

518

</term>

519

520

<para>

521

This is the actual program which talks to this server.

522

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

523

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

524

fully started system.

525

</para>

526

</listitem>

527

</varlistentry>

528

529

<term>

530

554

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

531

555

</term>

532

556

549

573

</varlistentry>

550

574

551

575

<term>

552

<ulink

553

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

576

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

577

>GnuTLS</ulink>

554

578

</term>

555

579

556

580

<para>

562

586

</varlistentry>

563

587

564

588

<term>

565

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

566

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

567

Unicast Addresses</citation>

589

RFC 4291: <citetitle>IP Version 6 Addressing

590

Architecture</citetitle>

568

591

</term>

569

592

570

<para>

571

The clients use IPv6 link-local addresses, which are

572

immediately usable since a link-local addresses is

573

automatically assigned to a network interfaces when it is

574

brought up.

575

</para>

593

594

595

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

596

Addresses</citetitle></term>

597

598

</varlistentry>

599

600

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

601

Address</citetitle></term>

602

603

</varlistentry>

604

605

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

606

Addresses</citetitle></term>

607

608

<para>

609

The clients use IPv6 link-local addresses, which are

610

immediately usable since a link-local addresses is

611

automatically assigned to a network interfaces when it

612

is brought up.

613

</para>

614

</listitem>

615

</varlistentry>

616

</variablelist>

576

617

</listitem>

577

618

</varlistentry>

578

619

579

620

<term>

580

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

581

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

621

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

622

Protocol Version 1.1</citetitle>

582

623

</term>

583

624

584

625

<para>

588

629

</varlistentry>

589

630

590

631

<term>

591

<citation>RFC 4880: <citetitle>OpenPGP Message

592

Format</citetitle></citation>

632

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

593

633

</term>

594

634

595

635

<para>

599

639

</varlistentry>

600

640

601

641

<term>

602

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

603

Transport Layer Security</citetitle></citation>

642

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

643

Security</citetitle>

604

644

</term>

605

645

606

646

<para>

612

652

</variablelist>

613

653

</refsect1>

614

654

</refentry>

655

656

657

658

659