/mandos/trunk : revision 89

3

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

4

<!ENTITY VERSION "1.0">

5

<!ENTITY COMMANDNAME "mandos">

6

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

6

<!ENTITY OVERVIEW SYSTEM "overview.xml">

7

]>

8

9

9

10

11

<title>Mandos Manual</title>

11

<title>&COMMANDNAME;</title>

12

13

<productname>Mandos</productname>

13

<productname>&COMMANDNAME;</productname>

14

<productnumber>&VERSION;</productnumber>

15

<date>&TIMESTAMP;</date>

16

15

17

16

18

17

<firstname>Björn</firstname>

34

33

<holder>Teddy Hogeborn</holder>

35

34

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

36

35

</copyright>

37

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

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>

38

59

</refentryinfo>

39

60

40

61

45

66

46

67

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

47

68

48

Gives encrypted passwords to authenticated Mandos clients

69

Sends encrypted passwords to authenticated Mandos clients

49

70

</refpurpose>

50

71

</refnamediv>

51

72

52

73

53

74

54

75

<command>&COMMANDNAME;</command>

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>

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>

86

93

</cmdsynopsis>

87

94

88

95

<command>&COMMANDNAME;</command>

89

96

90

91

97

98

92

99

</group>

93

100

</cmdsynopsis>

94

101

95

102

<command>&COMMANDNAME;</command>

96

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

103

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

97

104

</cmdsynopsis>

98

105

99

106

<command>&COMMANDNAME;</command>

100

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

107

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

101

108

</cmdsynopsis>

102

109

</refsynopsisdiv>

103

110

127

134

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

128

135

linkend="overview"/> for details.

129

136

</para>

130

137

131

138

</refsect1>

132

139

133

140

134

141

<title>OPTIONS</title>

135

142

136

143

137

144

138

139

145

140

146

141

147

<para>

142

148

Show a help message and exit

143

149

</para>

144

150

</listitem>

145

151

</varlistentry>

146

147

148

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

149

150

151

152

153

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

154

</listitem>

155

</varlistentry>

156

157

158

<term><option>--address

159

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

160

<term><option>-a

161

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

162

163

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

164

</listitem>

165

</varlistentry>

166

167

168

<term><option>--port

169

170

<term><option>-p

171

172

173

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

174

</listitem>

175

</varlistentry>

176

177

178

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

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>

179

198

180

199

<para>

181

200

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

183

202

</para>

184

203

</listitem>

185

204

</varlistentry>

186

187

188

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

189

190

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

191

</listitem>

192

</varlistentry>

193

194

195

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

196

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

197

198

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

199

</listitem>

200

</varlistentry>

201

202

203

<term><option>--servicename

204

205

206

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

207

xpointer="servicename"/>

208

</listitem>

209

</varlistentry>

210

211

212

<term><option>--configdir

213

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

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

252

253

254

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

255

</literal></term>

214

256

215

257

<para>

216

258

Directory to search for configuration files. Default is

224

266

</varlistentry>

225

267

226

268

227

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

269

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

228

270

229

271

<para>

230

272

Prints the program version and exit.

236

278

237

279

238

280

<title>OVERVIEW</title>

239

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

281

&OVERVIEW;

240

282

<para>

241

283

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

242

284

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

243

<acronym>RAM</acronym> disk environment.

285

RAM disk environment.

244

286

</para>

245

287

</refsect1>

246

288

275

317

276

318

</row>

277

319

<row>

278

320

279

321

280

322

</row>

281

323

<row>

311

353

longer eligible to receive the encrypted password. The timeout,

312

354

checker program, and interval between checks can be configured

313

355

both globally and per client; see <citerefentry>

356

<refentrytitle>mandos.conf</refentrytitle>

357

314

358

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

315

359

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

316

360

</para>

319

363

320

364

<title>LOGGING</title>

321

365

<para>

322

The server will send log message with various severity levels to

323

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

366

The server will send log messaged with various severity levels

367

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

324

368

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

325

369

and also show them on the console.

326

370

</para>

338

382

<title>ENVIRONMENT</title>

339

383

340

384

341

385

342

386

343

387

<para>

344

388

To start the configured checker (see <xref

347

391

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

348

392

an absolute path is not given. See <citerefentry>

349

393

350

</citerefentry>.

394

</citerefentry>

351

395

</para>

352

396

</listitem>

353

397

</varlistentry>

449

493

Normal invocation needs no options:

450

494

</para>

451

495

<para>

452

<userinput>&COMMANDNAME;</userinput>

496

<userinput>mandos</userinput>

453

497

</para>

454

498

</informalexample>

455

499

462

506

<para>

463

507

464

508

465

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

509

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

466

510

467

511

</para>

468

512

</informalexample>

474

518

<para>

475

519

476

520

477

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

521

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

478

522

479

523

</para>

480

524

</informalexample>

521

565

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

522

566

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

523

567

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

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

527

571

configuration file to omit any suspect clients, and restart

528

572

the server program.

529

573

</para>

537

581

538

582

539

583

540

<para>

541

542

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

543

544

<refentrytitle>mandos.conf</refentrytitle>

545

546

<refentrytitle>password-request</refentrytitle>

547

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

548

549

</citerefentry>

550

</para>

551

584

552

585

553

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>

554

603

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

555

604

</term>

556

605

573

622

</varlistentry>

574

623

575

624

<term>

576

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

577

>GnuTLS</ulink>

625

<ulink

626

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

578

627

</term>

579

628

580

629

<para>

586

635

</varlistentry>

587

636

588

637

<term>

589

RFC 4291: <citetitle>IP Version 6 Addressing

590

Architecture</citetitle>

638

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

639

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

640

Unicast Addresses</citation>

591

641

</term>

592

642

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>

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>

617

649

</listitem>

618

650

</varlistentry>

619

651

620

652

<term>

621

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

622

Protocol Version 1.1</citetitle>

653

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

654

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

623

655

</term>

624

656

625

657

<para>

629

661

</varlistentry>

630

662

631

663

<term>

632

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

664

<citation>RFC 4880: <citetitle>OpenPGP Message

665

Format</citetitle></citation>

633

666

</term>

634

667

635

668

<para>

639

672

</varlistentry>

640

673

641

674

<term>

642

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

643

Security</citetitle>

675

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

676

Transport Layer Security</citetitle></citation>

644

677

</term>

645

678

646

679

<para>

652

685

</variablelist>

653

686

</refsect1>

654

687

</refentry>

655

656

657

658

659