/mandos/release

« back to all changes in this revision

Viewing changes to mandos-clients.conf.xml

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

• reverse the comparison (361 to 237.2.205)
• stop comparing with revision 237.2.205

Show diffs side-by-side

added

removed

mandos-clients.conf.xml

3

3

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

4

4

<!ENTITY CONFNAME "mandos-clients.conf">

5

5

<!ENTITY CONFPATH "<filename>/etc/mandos/clients.conf</filename>">

6

 

<!ENTITY TIMESTAMP "2010-09-25">

 

6

<!ENTITY TIMESTAMP "2017-02-23">

7

7

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

8

8

%common;

9

9

]>

20

20

        <firstname>Björn</firstname>

21

21

        <surname>Påhlsson</surname>

22

22

        <address>

23

 

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

 

23

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

24

24

        </address>

25

25

      </author>

26

26

      <author>

27

27

        <firstname>Teddy</firstname>

28

28

        <surname>Hogeborn</surname>

29

29

        <address>

30

 

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

 

30

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

31

31

        </address>

32

32

      </author>

33

33

    </authorgroup>

34

34

    <copyright>

35

35

      <year>2008</year>

36

36

      <year>2009</year>

 

37

      <year>2010</year>

 

38

      <year>2011</year>

 

39

      <year>2012</year>

 

40

      <year>2013</year>

 

41

      <year>2014</year>

 

42

      <year>2015</year>

 

43

      <year>2016</year>

 

44

      <year>2017</year>

37

45

      <holder>Teddy Hogeborn</holder>

38

46

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

39

47

    </copyright>

63

71

      ><refentrytitle>mandos</refentrytitle>

64

72

      <manvolnum>8</manvolnum></citerefentry>, read by it at startup.

65

73

      The file needs to list all clients that should be able to use

66

 

      the service.  All clients listed will be regarded as enabled,

67

 

      even if a client was disabled in a previous run of the server.

 

74

      the service.  The settings in this file can be overridden by

 

75

      runtime changes to the server, which it saves across restarts.

 

76

      (See the section called <quote>PERSISTENT STATE</quote> in

 

77

      <citerefentry><refentrytitle>mandos</refentrytitle><manvolnum

 

78

      >8</manvolnum></citerefentry>.)  However, any <emphasis

 

79

      >changes</emphasis> to this file (including adding and removing

 

80

      clients) will, at startup, override changes done during runtime.

68

81

    </para>

69

82

    <para>

70

83

      The format starts with a <literal>[<replaceable>section

109

122

          <para>

110

123

            How long to wait for external approval before resorting to

111

124

            use the <option>approved_by_default</option> value.  The

112

 

            default is <quote>0s</quote>, i.e. not to wait.

 

125

            default is <quote>PT0S</quote>, i.e. not to wait.

113

126

          </para>

114

127

          <para>

115

128

            The format of <replaceable>TIME</replaceable> is the same

159

172

            This option is <emphasis>optional</emphasis>.

160

173

          </para>

161

174

          <para>

162

 

            This option allows you to override the default shell

163

 

            command that the server will use to check if the client is

164

 

            still up.  Any output of the command will be ignored, only

165

 

            the exit code is checked:  If the exit code of the command

166

 

            is zero, the client is considered up.  The command will be

167

 

            run using <quote><command><filename>/bin/sh</filename>

 

175

            This option overrides the default shell command that the

 

176

            server will use to check if the client is still up.  Any

 

177

            output of the command will be ignored, only the exit code

 

178

            is checked:  If the exit code of the command is zero, the

 

179

            client is considered up.  The command will be run using

 

180

            <quote><command><filename>/bin/sh</filename>

168

181

            <option>-c</option></command></quote>, so

169

182

            <varname>PATH</varname> will be searched.  The default

170

183

            value for the checker command is <quote><literal

171

184

            ><command>fping</command> <option>-q</option> <option

172

 

            >--</option> %%(host)s</literal></quote>.

 

185

            >--</option> %%(host)s</literal></quote>.  Note that

 

186

            <command>mandos-keygen</command>, when generating output

 

187

            to be inserted into this file, normally looks for an SSH

 

188

            server on the Mandos client, and, if it find one, outputs

 

189

            a <option>checker</option> option to check for the

 

190

            client’s key fingerprint – this is more secure against

 

191

            spoofing.

173

192

          </para>

174

193

          <para>

175

194

            In addition to normal start time expansion, this option

180

199

      </varlistentry>

181

200

      

182

201

      <varlistentry>

 

202

        <term><option>extended_timeout<literal> = </literal><replaceable

 

203

        >TIME</replaceable></option></term>

 

204

        <listitem>

 

205

          <para>

 

206

            This option is <emphasis>optional</emphasis>.

 

207

          </para>

 

208

          <para>

 

209

            Extended timeout is an added timeout that is given once

 

210

            after a password has been sent successfully to a client.

 

211

            The timeout is by default longer than the normal timeout,

 

212

            and is used for handling the extra long downtime while a

 

213

            machine is booting up.  Time to take into consideration

 

214

            when changing this value is file system checks and quota

 

215

            checks.  The default value is 15 minutes.

 

216

          </para>

 

217

          <para>

 

218

            The format of <replaceable>TIME</replaceable> is the same

 

219

            as for <varname>timeout</varname> below.

 

220

          </para>

 

221

        </listitem>

 

222

      </varlistentry>

 

223

      

 

224

      <varlistentry>

183

225

        <term><option>fingerprint<literal> = </literal

184

226

        ><replaceable>HEXSTRING</replaceable></option></term>

185

227

        <listitem>

189

231

          <para>

190

232

            This option sets the OpenPGP fingerprint that identifies

191

233

            the public key that clients authenticate themselves with

192

 

            through TLS.  The string needs to be in hexidecimal form,

 

234

            through TLS.  The string needs to be in hexadecimal form,

193

235

            but spaces or upper/lower case are not significant.

194

236

          </para>

195

237

        </listitem>

227

269

            will wait for a checker to complete until the below

228

270

            <quote><varname>timeout</varname></quote> occurs, at which

229

271

            time the client will be disabled, and any running checker

230

 

            killed.  The default interval is 5 minutes.

 

272

            killed.  The default interval is 2 minutes.

231

273

          </para>

232

274

          <para>

233

275

            The format of <replaceable>TIME</replaceable> is the same

297

339

            This option is <emphasis>optional</emphasis>.

298

340

          </para>

299

341

          <para>

300

 

            The timeout is how long the server will wait (for either a

301

 

            successful checker run or a client receiving its secret)

302

 

            until a client is disabled and not allowed to get the data

303

 

            this server holds.  By default Mandos will use 1 hour.

304

 

          </para>

305

 

          <para>

306

 

            The <replaceable>TIME</replaceable> is specified as a

307

 

            space-separated number of values, each of which is a

308

 

            number and a one-character suffix.  The suffix must be one

309

 

            of <quote>d</quote>, <quote>s</quote>, <quote>m</quote>,

310

 

            <quote>h</quote>, and <quote>w</quote> for days, seconds,

311

 

            minutes, hours, and weeks, respectively.  The values are

312

 

            added together to give the total time value, so all of

313

 

            <quote><literal>330s</literal></quote>,

314

 

            <quote><literal>110s 110s 110s</literal></quote>, and

315

 

            <quote><literal>5m 30s</literal></quote> will give a value

316

 

            of five minutes and thirty seconds.

 

342

            The timeout is how long the server will wait, after a

 

343

            successful checker run, until a client is disabled and not

 

344

            allowed to get the data this server holds.  By default

 

345

            Mandos will use 5 minutes.  See also the

 

346

            <option>extended_timeout</option> option.

 

347

          </para>

 

348

          <para>

 

349

            The <replaceable>TIME</replaceable> is specified as an RFC

 

350

            3339 duration; for example

 

351

            <quote><literal>P1Y2M3DT4H5M6S</literal></quote> meaning

 

352

            one year, two months, three days, four hours, five

 

353

            minutes, and six seconds.  Some values can be omitted, see

 

354

            RFC 3339 Appendix A for details.

 

355

          </para>

 

356

        </listitem>

 

357

      </varlistentry>

 

358

      

 

359

      <varlistentry>

 

360

        <term><option>enabled<literal> = </literal>{ <literal

 

361

        >1</literal> | <literal>yes</literal> | <literal>true</literal

 

362

        > | <literal >on</literal> | <literal>0</literal> | <literal

 

363

        >no</literal> | <literal>false</literal> | <literal

 

364

        >off</literal> }</option></term>

 

365

        <listitem>

 

366

          <para>

 

367

            Whether this client should be enabled by default.  The

 

368

            default is <quote>true</quote>.

317

369

          </para>

318

370

        </listitem>

319

371

      </varlistentry>

356

408

        <quote><literal>%%(<replaceable>foo</replaceable>)s</literal

357

409

        ></quote> will be replaced by the value of the attribute

358

410

        <varname>foo</varname> of the internal

359

 

        <quote><classname>Client</classname></quote> object.  See the

360

 

        source code for details, and let the authors know of any

361

 

        attributes that are useful so they may be preserved to any new

362

 

        versions of this software.

 

411

        <quote><classname>Client</classname></quote> object in the

 

412

        Mandos server.  The currently allowed values for

 

413

        <replaceable>foo</replaceable> are:

 

414

        <quote><literal>approval_delay</literal></quote>,

 

415

        <quote><literal>approval_duration</literal></quote>,

 

416

        <quote><literal>created</literal></quote>,

 

417

        <quote><literal>enabled</literal></quote>,

 

418

        <quote><literal>expires</literal></quote>,

 

419

        <quote><literal>fingerprint</literal></quote>,

 

420

        <quote><literal>host</literal></quote>,

 

421

        <quote><literal>interval</literal></quote>,

 

422

        <quote><literal>last_approval_request</literal></quote>,

 

423

        <quote><literal>last_checked_ok</literal></quote>,

 

424

        <quote><literal>last_enabled</literal></quote>,

 

425

        <quote><literal>name</literal></quote>,

 

426

        <quote><literal>timeout</literal></quote>, and, if using

 

427

        D-Bus, <quote><literal>dbus_object_path</literal></quote>.

 

428

        See the source code for details.  <emphasis role="strong"

 

429

        >Currently, <emphasis>none</emphasis> of these attributes

 

430

        except <quote><literal>host</literal></quote> are guaranteed

 

431

        to be valid in future versions.</emphasis> Therefore, please

 

432

        let the authors know of any attributes that are useful so they

 

433

        may be preserved to any new versions of this software.

363

434

      </para>

364

435

      <para>

365

436

        Note that this means that, in order to include an actual

393

464

      <literal>%(<replaceable>foo</replaceable>)s</literal> is

394

465

      obscure.

395

466

    </para>

 

467

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

396

468

  </refsect1>

397

469

  

398

470

  <refsect1 id="example">

400

472

    <informalexample>

401

473

      <programlisting>

402

474

[DEFAULT]

403

 

timeout = 1h

404

 

interval = 5m

 

475

timeout = PT5M

 

476

interval = PT2M

405

477

checker = fping -q -- %%(host)s

406

478

 

407

479

# Client "foo"

424

496

        4T2zw4dxS5NswXWU0sVEXxjs6PYxuIiCTL7vdpx8QjBkrPWDrAbcMyBr2O

425

497

        QlnHIvPzEArRQLo=

426

498

host = foo.example.org

427

 

interval = 1m

 

499

interval = PT1M

428

500

 

429

501

# Client "bar"

430

502

[bar]

431

503

fingerprint = 3e393aeaefb84c7e89e2f547b3a107558fca3a27

432

504

secfile = /etc/mandos/bar-secret

433

 

timeout = 15m

 

505

timeout = PT15M

434

506

approved_by_default = False

435

 

approval_delay = 30s

 

507

approval_delay = PT30S

436

508

      </programlisting>

437

509

    </informalexample>

438

510

  </refsect1>

440

512

  <refsect1 id="see_also">

441

513

    <title>SEE ALSO</title>

442

514

    <para>

 

515

      <citerefentry><refentrytitle>intro</refentrytitle>

 

516

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

443

517

      <citerefentry><refentrytitle>mandos-keygen</refentrytitle>

444

518

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

445

519

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

446

520

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

447

521

      <citerefentry><refentrytitle>mandos</refentrytitle>

 

522

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

 

523

      <citerefentry><refentrytitle>fping</refentrytitle>

448

524

      <manvolnum>8</manvolnum></citerefentry>

449

525

    </para>

 

526

    <variablelist>

 

527

      <varlistentry>

 

528

        <term>

 

529

          RFC 3339: <citetitle>Date and Time on the Internet:

 

530

          Timestamps</citetitle>

 

531

        </term>

 

532

      <listitem>

 

533

        <para>

 

534

          The time intervals are in the "duration" format, as

 

535

          specified in ABNF in Appendix A of RFC 3339.

 

536

        </para>

 

537

      </listitem>

 

538

      </varlistentry>

 

539

    </variablelist>

450

540

  </refsect1>

451

541

</refentry>

452

542

<!-- Local Variables: -->

• Older »

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