/mandos/release : revision 148

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

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

122

115

Any authenticated client is then given the stored pre-encrypted

123

116

password for that specific client.

124

117

</para>

125

126

118

</refsect1>

127

119

128

120

129

121

<title>PURPOSE</title>

130

131

122

<para>

132

123

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

133

124

rebooting</emphasis> of client host computer with an

134

125

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

135

126

linkend="overview"/> for details.

136

127

</para>

137

138

128

</refsect1>

139

129

140

130

141

131

<title>OPTIONS</title>

142

143

132

144

133

145

134

135

146

136

147

137

<para>

148

138

Show a help message and exit

149

139

</para>

150

140

</listitem>

151

141

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

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>

198

175

199

176

<para>

200

177

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

202

179

</para>

203

180

</listitem>

204

181

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

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>

255

210

256

211

<para>

257

212

Directory to search for configuration files. Default is

265

220

</varlistentry>

266

221

267

222

268

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

223

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

269

224

270

225

<para>

271

226

Prints the program version and exit.

277

232

278

233

279

234

<title>OVERVIEW</title>

280

&OVERVIEW;

235

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

281

236

<para>

282

237

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

283

238

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

284

RAM disk environment.

239

<acronym>RAM</acronym> disk environment.

285

240

</para>

286

241

</refsect1>

287

242

316

271

317

272

</row>

318

273

<row>

319

274

320

275

321

276

</row>

322

277

<row>

352

307

longer eligible to receive the encrypted password. The timeout,

353

308

checker program, and interval between checks can be configured

354

309

both globally and per client; see <citerefentry>

355

<refentrytitle>mandos.conf</refentrytitle>

356

357

310

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

358

311

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

359

312

</para>

362

315

363

316

<title>LOGGING</title>

364

317

<para>

365

The server will send log messaged with various severity levels

366

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

367

320

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

368

321

and also show them on the console.

369

322

</para>

381

334

<title>ENVIRONMENT</title>

382

335

383

336

384

337

385

338

386

339

<para>

387

340

To start the configured checker (see <xref

390

343

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

391

344

an absolute path is not given. See <citerefentry>

392

345

393

</citerefentry>

346

</citerefentry>.

394

347

</para>

395

348

</listitem>

396

349

</varlistentry>

492

445

Normal invocation needs no options:

493

446

</para>

494

447

<para>

495

<userinput>mandos</userinput>

448

<userinput>&COMMANDNAME;</userinput>

496

449

</para>

497

450

</informalexample>

498

451

505

458

<para>

506

459

507

460

508

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

461

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

509

462

510

463

</para>

511

464

</informalexample>

517

470

<para>

518

471

519

472

520

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

473

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

521

474

522

475

</para>

523

476

</informalexample>

561

514

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

562

515

regard all clients therein as valid, and hence eligible to

563

516

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.

517

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

518

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

519

fake Mandos client with the keys from the non-encrypted

520

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

521

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

522

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

523

configuration file to omit any suspect clients, and restart

524

the server program.

571

525

</para>

572

526

<para>

573

527

For more details on client-side security, see

579

533

580

534

581

535

536

<para>

537

538

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

539

540

<refentrytitle>mandos.conf</refentrytitle>

541

542

<refentrytitle>password-request</refentrytitle>

543

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

544

545

</citerefentry>

546

</para>

582

547

583

548

584

549

<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

550

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

602

551

</term>

603

552

620

569

</varlistentry>

621

570

622

571

<term>

623

<ulink

624

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

572

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

573

>GnuTLS</ulink>

625

574

</term>

626

575

627

576

<para>

633

582

</varlistentry>

634

583

635

584

<term>

636

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

637

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

638

Unicast Addresses</citation>

585

RFC 4291: <citetitle>IP Version 6 Addressing

586

Architecture</citetitle>

639

587

</term>

640

588

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>

589

590

591

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

592

Addresses</citetitle></term>

593

594

</varlistentry>

595

596

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

597

Address</citetitle></term>

598

599

</varlistentry>

600

601

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

602

Addresses</citetitle></term>

603

604

<para>

605

The clients use IPv6 link-local addresses, which are

606

immediately usable since a link-local addresses is

607

automatically assigned to a network interfaces when it

608

is brought up.

609

</para>

610

</listitem>

611

</varlistentry>

612

</variablelist>

647

613

</listitem>

648

614

</varlistentry>

649

615

650

616

<term>

651

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

652

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

617

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

618

Protocol Version 1.1</citetitle>

653

619

</term>

654

620

655

621

<para>

659

625

</varlistentry>

660

626

661

627

<term>

662

<citation>RFC 4880: <citetitle>OpenPGP Message

663

Format</citetitle></citation>

628

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

664

629

</term>

665

630

666

631

<para>

670

635

</varlistentry>

671

636

672

637

<term>

673

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

674

Transport Layer Security</citetitle></citation>

638

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

639

Security</citetitle>

675

640

</term>

676

641

677

642

<para>

683

648

</variablelist>

684

649

</refsect1>

685

650

</refentry>

651

652

653

654

655