/mandos/release : revision 133

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>

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

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>

93

86

</cmdsynopsis>

94

87

95

88

<command>&COMMANDNAME;</command>

96

89

97

98

90

91

99

92

</group>

100

93

</cmdsynopsis>

101

94

102

95

<command>&COMMANDNAME;</command>

103

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

96

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

104

97

</cmdsynopsis>

105

98

106

99

<command>&COMMANDNAME;</command>

107

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

100

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

108

101

</cmdsynopsis>

109

102

</refsynopsisdiv>

110

103

134

127

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

135

128

linkend="overview"/> for details.

136

129

</para>

137

130

138

131

</refsect1>

139

132

140

133

141

134

<title>OPTIONS</title>

142

135

143

136

144

137

145

138

139

146

140

147

141

<para>

148

142

Show a help message and exit

149

143

</para>

150

144

</listitem>

151

145

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

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>

198

179

199

180

<para>

200

181

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

202

183

</para>

203

184

</listitem>

204

185

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

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>

255

214

256

215

<para>

257

216

Directory to search for configuration files. Default is

265

224

</varlistentry>

266

225

267

226

268

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

227

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

269

228

270

229

<para>

271

230

Prints the program version and exit.

277

236

278

237

279

238

<title>OVERVIEW</title>

280

&OVERVIEW;

239

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

281

240

<para>

282

241

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

283

242

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

316

275

317

276

</row>

318

277

<row>

319

278

320

279

321

280

</row>

322

281

<row>

352

311

longer eligible to receive the encrypted password. The timeout,

353

312

checker program, and interval between checks can be configured

354

313

both globally and per client; see <citerefentry>

355

<refentrytitle>mandos.conf</refentrytitle>

356

357

314

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

358

315

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

359

316

</para>

362

319

363

320

<title>LOGGING</title>

364

321

<para>

365

The server will send log messaged with various severity levels

366

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

322

The server will send log message with various severity levels to

323

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

367

324

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

368

325

and also show them on the console.

369

326

</para>

381

338

<title>ENVIRONMENT</title>

382

339

383

340

384

341

385

342

386

343

<para>

387

344

To start the configured checker (see <xref

390

347

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

391

348

an absolute path is not given. See <citerefentry>

392

349

393

</citerefentry>

350

</citerefentry>.

394

351

</para>

395

352

</listitem>

396

353

</varlistentry>

492

449

Normal invocation needs no options:

493

450

</para>

494

451

<para>

495

<userinput>mandos</userinput>

452

<userinput>&COMMANDNAME;</userinput>

496

453

</para>

497

454

</informalexample>

498

455

505

462

<para>

506

463

507

464

508

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

465

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

509

466

510

467

</para>

511

468

</informalexample>

517

474

<para>

518

475

519

476

520

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

477

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

521

478

522

479

</para>

523

480

</informalexample>

561

518

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

562

519

regard all clients therein as valid, and hence eligible to

563

520

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.

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 RAM image of the client host. What should be done in

525

that case (if restarting the server program really is

526

necessary) is to stop the server program, edit the

527

configuration file to omit any suspect clients, and restart

528

the server program.

571

529

</para>

572

530

<para>

573

531

For more details on client-side security, see

579

537

580

538

581

539

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>

582

551

583

552

584

553

<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

554

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

602

555

</term>

603

556

620

573

</varlistentry>

621

574

622

575

<term>

623

<ulink

624

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

576

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

577

>GnuTLS</ulink>

625

578

</term>

626

579

627

580

<para>

633

586

</varlistentry>

634

587

635

588

<term>

636

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

637

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

638

Unicast Addresses</citation>

589

RFC 4291: <citetitle>IP Version 6 Addressing

590

Architecture</citetitle>

639

591

</term>

640

592

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>

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>

647

617

</listitem>

648

618

</varlistentry>

649

619

650

620

<term>

651

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

652

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

621

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

622

Protocol Version 1.1</citetitle>

653

623

</term>

654

624

655

625

<para>

659

629

</varlistentry>

660

630

661

631

<term>

662

<citation>RFC 4880: <citetitle>OpenPGP Message

663

Format</citetitle></citation>

632

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

664

633

</term>

665

634

666

635

<para>

670

639

</varlistentry>

671

640

672

641

<term>

673

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

674

Transport Layer Security</citetitle></citation>

642

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

643

Security</citetitle>

675

644

</term>

676

645

677

646

<para>

683

652

</variablelist>

684

653

</refsect1>

685

654

</refentry>

655

656

657

658

659