/mandos/trunk : revision 126

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

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>

66

67

67

68

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

68

69

69

Sends encrypted passwords to authenticated Mandos clients

70

Gives encrypted passwords to authenticated Mandos clients

70

71

</refpurpose>

71

72

</refnamediv>

72

73

74

74

75

75

76

<command>&COMMANDNAME;</command>

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>

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>

93

108

</cmdsynopsis>

94

109

95

110

<command>&COMMANDNAME;</command>

96

111

97

98

112

113

99

114

</group>

100

115

</cmdsynopsis>

101

116

102

117

<command>&COMMANDNAME;</command>

103

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

118

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

104

119

</cmdsynopsis>

105

120

106

121

<command>&COMMANDNAME;</command>

107

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

122

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

108

123

</cmdsynopsis>

109

124

</refsynopsisdiv>

110

125

134

149

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

135

150

linkend="overview"/> for details.

136

151

</para>

137

152

138

153

</refsect1>

139

154

140

155

141

156

<title>OPTIONS</title>

142

157

143

158

144

159

145

160

161

146

162

147

163

<para>

148

164

Show a help message and exit

149

165

</para>

150

166

</listitem>

151

167

</varlistentry>

152

153

154

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

155

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

156

157

<para>

158

Only announce the server and listen to requests on network

159

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

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>

166

167

168

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

169

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

170

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>

181

</listitem>

182

</varlistentry>

183

184

185

186

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

187

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>

193

</listitem>

194

</varlistentry>

195

196

197

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

168

169

170

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

171

172

173

174

175

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

176

</listitem>

177

</varlistentry>

178

179

180

<term><option>--address

181

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

182

<term><option>-a

183

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

184

185

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

186

</listitem>

187

</varlistentry>

188

189

190

<term><option>--port

191

192

<term><option>-p

193

194

195

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

196

</listitem>

197

</varlistentry>

198

199

200

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

198

201

199

202

<para>

200

203

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

202

205

</para>

203

206

</listitem>

204

207

</varlistentry>

205

206

207

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

208

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>

214

</listitem>

215

</varlistentry>

216

217

218

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

219

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

220

221

<para>

222

GnuTLS priority string for the TLS handshake with the

223

clients. The default is

224

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

225

See <citerefentry><refentrytitle>gnutls_priority_init

226

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

227

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

228

this may make the TLS handshake fail, making communication

229

with clients impossible.

230

</para>

231

</listitem>

232

</varlistentry>

233

234

235

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

236

</literal></term>

237

238

<para>

239

Zeroconf service name. The default is

240

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

241

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

242

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

243

which would not normally be useful. If there are name

244

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

245

newer server will automatically rename itself to

246

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

247

therefore, this option is not needed in that case.

248

</para>

249

</listitem>

250

</varlistentry>

251

252

253

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

254

</literal></term>

208

209

210

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

211

212

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

213

</listitem>

214

</varlistentry>

215

216

217

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

218

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

219

220

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

221

</listitem>

222

</varlistentry>

223

224

225

<term><option>--servicename

226

227

228

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

229

xpointer="servicename"/>

230

</listitem>

231

</varlistentry>

232

233

234

<term><option>--configdir

235

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

255

236

256

237

<para>

257

238

Directory to search for configuration files. Default is

265

246

</varlistentry>

266

247

267

248

268

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

249

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

269

250

270

251

<para>

271

252

Prints the program version and exit.

277

258

278

259

279

260

<title>OVERVIEW</title>

280

&OVERVIEW;

261

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

281

262

<para>

282

263

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

283

264

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

316

297

317

298

</row>

318

299

<row>

319

300

320

301

321

302

</row>

322

303

<row>

352

333

longer eligible to receive the encrypted password. The timeout,

353

334

checker program, and interval between checks can be configured

354

335

both globally and per client; see <citerefentry>

355

<refentrytitle>mandos.conf</refentrytitle>

356

357

336

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

358

337

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

359

338

</para>

362

341

363

342

<title>LOGGING</title>

364

343

<para>

365

The server will send log messaged with various severity levels

366

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

344

The server will send log message with various severity levels to

345

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

367

346

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

368

347

and also show them on the console.

369

348

</para>

381

360

<title>ENVIRONMENT</title>

382

361

383

362

384

363

385

364

386

365

<para>

387

366

To start the configured checker (see <xref

390

369

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

391

370

an absolute path is not given. See <citerefentry>

392

371

393

</citerefentry>

372

</citerefentry>.

394

373

</para>

395

374

</listitem>

396

375

</varlistentry>

492

471

Normal invocation needs no options:

493

472

</para>

494

473

<para>

495

<userinput>mandos</userinput>

474

<userinput>&COMMANDNAME;</userinput>

496

475

</para>

497

476

</informalexample>

498

477

505

484

<para>

506

485

507

486

508

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

487

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

509

488

510

489

</para>

511

490

</informalexample>

517

496

<para>

518

497

519

498

520

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

499

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

521

500

522

501

</para>

523

502

</informalexample>

561

540

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

562

541

regard all clients therein as valid, and hence eligible to

563

542

receive their passwords. Therefore, be careful when

564

restarting servers if you suspect that a client has, in fact,

565

been compromised by parties who may now be running a fake

566

Mandos client with the keys from the non-encrypted initial RAM

567

image of the client host. What should be done in that case

568

(if restarting the server program really is necessary) is to

569

stop the server program, edit the configuration file to omit

570

any suspect clients, and restart the server program.

543

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

544

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

545

fake Mandos client with the keys from the non-encrypted

546

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

547

that case (if restarting the server program really is

548

necessary) is to stop the server program, edit the

549

configuration file to omit any suspect clients, and restart

550

the server program.

571

551

</para>

572

552

<para>

573

553

For more details on client-side security, see

579

559

580

560

581

561

562

<para>

563

564

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

565

566

<refentrytitle>mandos.conf</refentrytitle>

567

568

<refentrytitle>password-request</refentrytitle>

569

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

570

571

</citerefentry>

572

</para>

582

573

583

574

584

575

<term>

585

586

<refentrytitle>password-request</refentrytitle>

587

<manvolnum>8mandos</manvolnum>

588

</citerefentry>

589

</term>

590

591

<para>

592

This is the actual program which talks to this server.

593

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

594

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

595

fully started system.

596

</para>

597

</listitem>

598

</varlistentry>

599

600

<term>

601

576

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

602

577

</term>

603

578

620

595

</varlistentry>

621

596

622

597

<term>

623

<ulink

624

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

598

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

599

>GnuTLS</ulink>

625

600

</term>

626

601

627

602

<para>

633

608

</varlistentry>

634

609

635

610

<term>

636

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

637

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

638

Unicast Addresses</citation>

611

RFC 4291: <citetitle>IP Version 6 Addressing

612

Architecture</citetitle>

639

613

</term>

640

614

641

<para>

642

The clients use IPv6 link-local addresses, which are

643

immediately usable since a link-local addresses is

644

automatically assigned to a network interfaces when it is

645

brought up.

646

</para>

615

616

617

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

618

Addresses</citetitle></term>

619

620

</varlistentry>

621

622

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

623

Address</citetitle></term>

624

625

</varlistentry>

626

627

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

628

Addresses</citetitle></term>

629

630

<para>

631

The clients use IPv6 link-local addresses, which are

632

immediately usable since a link-local addresses is

633

automatically assigned to a network interfaces when it

634

is brought up.

635

</para>

636

</listitem>

637

</varlistentry>

638

</variablelist>

647

639

</listitem>

648

640

</varlistentry>

649

641

650

642

<term>

651

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

652

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

643

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

644

Protocol Version 1.1</citetitle>

653

645

</term>

654

646

655

647

<para>

659

651

</varlistentry>

660

652

661

653

<term>

662

<citation>RFC 4880: <citetitle>OpenPGP Message

663

Format</citetitle></citation>

654

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

664

655

</term>

665

656

666

657

<para>

670

661

</varlistentry>

671

662

672

663

<term>

673

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

674

Transport Layer Security</citetitle></citation>

664

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

665

Security</citetitle>

675

666

</term>

676

667

677

668

<para>

683

674

</variablelist>

684

675

</refsect1>

685

676

</refentry>

677

678

679

680

681