/mandos/trunk

« back to all changes in this revision

Viewing changes to mandos.xml

• browse files at revision 406
• compare with another revision
• download diff
• download tarball
• view history from revision 406

• reverse the comparison (406 to 522)
• stop comparing with revision 522

Show diffs side-by-side

added

removed

mandos.xml

2

2

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"

3

3

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

4

4

<!ENTITY COMMANDNAME "mandos">

5

 

<!ENTITY TIMESTAMP "2011-10-22">

 

5

<!ENTITY TIMESTAMP "2009-09-17">

6

6

<!ENTITY % common SYSTEM "common.ent">

7

7

%common;

8

8

]>

19

19

        <firstname>Björn</firstname>

20

20

        <surname>Påhlsson</surname>

21

21

        <address>

22

 

          <email>belorn@recompile.se</email>

 

22

          <email>belorn@fukt.bsnet.se</email>

23

23

        </address>

24

24

      </author>

25

25

      <author>

26

26

        <firstname>Teddy</firstname>

27

27

        <surname>Hogeborn</surname>

28

28

        <address>

29

 

          <email>teddy@recompile.se</email>

 

29

          <email>teddy@fukt.bsnet.se</email>

30

30

        </address>

31

31

      </author>

32

32

    </authorgroup>

33

33

    <copyright>

34

34

      <year>2008</year>

35

35

      <year>2009</year>

36

 

      <year>2010</year>

37

 

      <year>2011</year>

38

36

      <holder>Teddy Hogeborn</holder>

39

37

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

40

38

    </copyright>

88

86

      <sbr/>

89

87

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

90

88

      <sbr/>

91

 

      <arg><option>--debuglevel

92

 

      <replaceable>LEVEL</replaceable></option></arg>

93

 

      <sbr/>

94

89

      <arg><option>--no-dbus</option></arg>

95

90

      <sbr/>

96

91

      <arg><option>--no-ipv6</option></arg>

97

 

      <sbr/>

98

 

      <arg><option>--no-restore</option></arg>

99

92

    </cmdsynopsis>

100

93

    <cmdsynopsis>

101

94

      <command>&COMMANDNAME;</command>

119

112

    <para>

120

113

      <command>&COMMANDNAME;</command> is a server daemon which

121

114

      handles incoming request for passwords for a pre-defined list of

122

 

      client host computers. For an introduction, see

123

 

      <citerefentry><refentrytitle>intro</refentrytitle>

124

 

      <manvolnum>8mandos</manvolnum></citerefentry>. The Mandos server

125

 

      uses Zeroconf to announce itself on the local network, and uses

126

 

      TLS to communicate securely with and to authenticate the

127

 

      clients.  The Mandos server uses IPv6 to allow Mandos clients to

128

 

      use IPv6 link-local addresses, since the clients will probably

129

 

      not have any other addresses configured (see <xref

130

 

      linkend="overview"/>).  Any authenticated client is then given

131

 

      the stored pre-encrypted password for that specific client.

 

115

      client host computers.  The Mandos server uses Zeroconf to

 

116

      announce itself on the local network, and uses TLS to

 

117

      communicate securely with and to authenticate the clients.  The

 

118

      Mandos server uses IPv6 to allow Mandos clients to use IPv6

 

119

      link-local addresses, since the clients will probably not have

 

120

      any other addresses configured (see <xref linkend="overview"/>).

 

121

      Any authenticated client is then given the stored pre-encrypted

 

122

      password for that specific client.

132

123

    </para>

133

124

  </refsect1>

134

125

  

203

194

      </varlistentry>

204

195

      

205

196

      <varlistentry>

206

 

        <term><option>--debuglevel

207

 

        <replaceable>LEVEL</replaceable></option></term>

208

 

        <listitem>

209

 

          <para>

210

 

            Set the debugging log level.

211

 

            <replaceable>LEVEL</replaceable> is a string, one of

212

 

            <quote><literal>CRITICAL</literal></quote>,

213

 

            <quote><literal>ERROR</literal></quote>,

214

 

            <quote><literal>WARNING</literal></quote>,

215

 

            <quote><literal>INFO</literal></quote>, or

216

 

            <quote><literal>DEBUG</literal></quote>, in order of

217

 

            increasing verbosity.  The default level is

218

 

            <quote><literal>WARNING</literal></quote>.

219

 

          </para>

220

 

        </listitem>

221

 

      </varlistentry>

222

 

      

223

 

      <varlistentry>

224

197

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

225

198

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

226

199

        <listitem>

277

250

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

278

251

        </listitem>

279

252

      </varlistentry>

280

 

      

281

 

      <varlistentry>

282

 

        <term><option>--no-restore</option></term>

283

 

        <listitem>

284

 

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

285

 

        </listitem>

286

 

      </varlistentry>

287

253

    </variablelist>

288

254

  </refsect1>

289

255

  

363

329

      for some time, the client is assumed to be compromised and is no

364

330

      longer eligible to receive the encrypted password.  (Manual

365

331

      intervention is required to re-enable a client.)  The timeout,

366

 

      extended timeout, checker program, and interval between checks

367

 

      can be configured both globally and per client; see

368

 

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

 

332

      checker program, and interval between checks can be configured

 

333

      both globally and per client; see <citerefentry>

 

334

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

369

335

      <manvolnum>5</manvolnum></citerefentry>.  A client successfully

370

336

      receiving its password will also be treated as a successful

371

337

      checker run.

372

338

    </para>

373

339

  </refsect1>

374

340

  

375

 

  <refsect1 id="approval">

376

 

    <title>APPROVAL</title>

377

 

    <para>

378

 

      The server can be configured to require manual approval for a

379

 

      client before it is sent its secret.  The delay to wait for such

380

 

      approval and the default action (approve or deny) can be

381

 

      configured both globally and per client; see <citerefentry>

382

 

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

383

 

      <manvolnum>5</manvolnum></citerefentry>.  By default all clients

384

 

      will be approved immediately without delay.

385

 

    </para>

386

 

    <para>

387

 

      This can be used to deny a client its secret if not manually

388

 

      approved within a specified time.  It can also be used to make

389

 

      the server delay before giving a client its secret, allowing

390

 

      optional manual denying of this specific client.

391

 

    </para>

392

 

    

393

 

  </refsect1>

394

 

  

395

341

  <refsect1 id="logging">

396

342

    <title>LOGGING</title>

397

343

    <para>

398

344

      The server will send log message with various severity levels to

399

 

      <filename class="devicefile">/dev/log</filename>.  With the

 

345

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

400

346

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

401

347

      and also show them on the console.

402

348

    </para>

407

353

    <para>

408

354

      The server will by default provide a D-Bus system bus interface.

409

355

      This interface will only be accessible by the root user or a

410

 

      Mandos-specific user, if such a user exists.  For documentation

411

 

      of the D-Bus API, see the file <filename>DBUS-API</filename>.

 

356

      Mandos-specific user, if such a user exists.

 

357

      <!-- XXX -->

412

358

    </para>

413

359

  </refsect1>

414

360

  

472

418

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

473

419

        <listitem>

474

420

          <para>

475

 

            The file containing the process id of the

476

 

            <command>&COMMANDNAME;</command> process started last.

 

421

            The file containing the process id of

 

422

            <command>&COMMANDNAME;</command>.

477

423

          </para>

478

424

        </listitem>

479

425

      </varlistentry>

480

426

      <varlistentry>

481

 

        <term><filename class="devicefile">/dev/log</filename></term>

 

427

        <term><filename>/dev/log</filename></term>

482

428

        <listitem>

483

429

          <para>

484

430

            The Unix domain socket to where local syslog messages are

507

453

      backtrace.  This could be considered a feature.

508

454

    </para>

509

455

    <para>

510

 

      Currently, if a client is disabled due to having timed out, the

511

 

      server does not record this fact onto permanent storage.  This

512

 

      has some security implications, see <xref linkend="clients"/>.

 

456

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

 

457

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

 

458

      permanent storage.  This has some security implications, see

 

459

      <xref linkend="clients"/>.

 

460

    </para>

 

461

    <para>

 

462

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

 

463

      status of clients, other than analyzing its <systemitem

 

464

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

513

465

    </para>

514

466

    <para>

515

467

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

518

470

      Debug mode is conflated with running in the foreground.

519

471

    </para>

520

472

    <para>

 

473

      The console log messages do not show a time stamp.

 

474

    </para>

 

475

    <para>

521

476

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

522

477

      keys.

523

478

    </para>

594

549

      </para>

595

550

      <para>

596

551

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

597

 

        by the server which would therefore disable the client.  But

598

 

        if the server was ever restarted, it would re-read its client

599

 

        list from its configuration file and again regard all clients

600

 

        therein as enabled, and hence eligible to receive their

601

 

        passwords.  Therefore, be careful when restarting servers if

602

 

        it is suspected that a client has, in fact, been compromised

603

 

        by parties who may now be running a fake Mandos client with

604

 

        the keys from the non-encrypted initial <acronym>RAM</acronym>

605

 

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

606

 

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

607

 

        stop the server program, edit the configuration file to omit

608

 

        any suspect clients, and restart the server program.

 

552

        by the server which would therefore declare the client

 

553

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

 

554

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

 

555

        regard all clients therein as valid, and hence eligible to

 

556

        receive their passwords.  Therefore, be careful when

 

557

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

 

558

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

 

559

        fake Mandos client with the keys from the non-encrypted

 

560

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

 

561

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

 

562

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

 

563

        configuration file to omit any suspect clients, and restart

 

564

        the server program.

609

565

      </para>

610

566

      <para>

611

567

        For more details on client-side security, see

618

574

  <refsect1 id="see_also">

619

575

    <title>SEE ALSO</title>

620

576

    <para>

621

 

      <citerefentry><refentrytitle>intro</refentrytitle>

622

 

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

623

 

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

624

 

      <manvolnum>5</manvolnum></citerefentry>,

625

 

      <citerefentry><refentrytitle>mandos.conf</refentrytitle>

626

 

      <manvolnum>5</manvolnum></citerefentry>,

627

 

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

628

 

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

629

 

      <citerefentry><refentrytitle>sh</refentrytitle>

630

 

      <manvolnum>1</manvolnum></citerefentry>

 

577

      <citerefentry>

 

578

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

 

579

        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>

 

580

        <refentrytitle>mandos.conf</refentrytitle>

 

581

        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>

 

582

        <refentrytitle>mandos-client</refentrytitle>

 

583

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

 

584

        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>

 

585

      </citerefentry>

631

586

    </para>

632

587

    <variablelist>

633

588

      <varlistentry>

• Older »

Loggerhead is a web-based interface for Breezy
Version: 2.0.2.dev0