/mandos/release

« back to all changes in this revision

Viewing changes to mandos-clients.conf.xml

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

• reverse the comparison (353 to 237.2.201)
• stop comparing with revision 237.2.201

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 "2016-06-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>

37

44

      <holder>Teddy Hogeborn</holder>

38

45

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

39

46

    </copyright>

63

70

      ><refentrytitle>mandos</refentrytitle>

64

71

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

65

72

      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.

 

73

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

 

74

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

 

75

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

 

76

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

 

77

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

 

78

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

 

79

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

68

80

    </para>

69

81

    <para>

70

82

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

109

121

          <para>

110

122

            How long to wait for external approval before resorting to

111

123

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

112

 

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

 

124

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

113

125

          </para>

114

126

          <para>

115

127

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

159

171

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

160

172

          </para>

161

173

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

 

174

            This option overrides the default shell command that the

 

175

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

 

176

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

 

177

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

 

178

            client is considered up.  The command will be run using

 

179

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

168

180

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

169

181

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

170

182

            value for the checker command is <quote><literal

171

183

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

172

 

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

 

184

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

 

185

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

 

186

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

 

187

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

 

188

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

 

189

            client’s key fingerprint – this is more secure against

 

190

            spoofing.

173

191

          </para>

174

192

          <para>

175

193

            In addition to normal start time expansion, this option

180

198

      </varlistentry>

181

199

      

182

200

      <varlistentry>

 

201

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

 

202

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

 

203

        <listitem>

 

204

          <para>

 

205

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

 

206

          </para>

 

207

          <para>

 

208

            Extended timeout is an added timeout that is given once

 

209

            after a password has been sent successfully to a client.

 

210

            The timeout is by default longer than the normal timeout,

 

211

            and is used for handling the extra long downtime while a

 

212

            machine is booting up.  Time to take into consideration

 

213

            when changing this value is file system checks and quota

 

214

            checks.  The default value is 15 minutes.

 

215

          </para>

 

216

          <para>

 

217

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

 

218

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

 

219

          </para>

 

220

        </listitem>

 

221

      </varlistentry>

 

222

      

 

223

      <varlistentry>

183

224

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

184

225

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

185

226

        <listitem>

189

230

          <para>

190

231

            This option sets the OpenPGP fingerprint that identifies

191

232

            the public key that clients authenticate themselves with

192

 

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

 

233

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

193

234

            but spaces or upper/lower case are not significant.

194

235

          </para>

195

236

        </listitem>

227

268

            will wait for a checker to complete until the below

228

269

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

229

270

            time the client will be disabled, and any running checker

230

 

            killed.  The default interval is 5 minutes.

 

271

            killed.  The default interval is 2 minutes.

231

272

          </para>

232

273

          <para>

233

274

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

297

338

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

298

339

          </para>

299

340

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

 

341

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

 

342

            successful checker run, until a client is disabled and not

 

343

            allowed to get the data this server holds.  By default

 

344

            Mandos will use 5 minutes.  See also the

 

345

            <option>extended_timeout</option> option.

 

346

          </para>

 

347

          <para>

 

348

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

 

349

            3339 duration; for example

 

350

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

 

351

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

 

352

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

 

353

            RFC 3339 Appendix A for details.

 

354

          </para>

 

355

        </listitem>

 

356

      </varlistentry>

 

357

      

 

358

      <varlistentry>

 

359

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

 

360

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

 

361

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

 

362

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

 

363

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

 

364

        <listitem>

 

365

          <para>

 

366

            Whether this client should be enabled by default.  The

 

367

            default is <quote>true</quote>.

317

368

          </para>

318

369

        </listitem>

319

370

      </varlistentry>

356

407

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

357

408

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

358

409

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

 

410

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

 

411

        Mandos server.  The currently allowed values for

 

412

        <replaceable>foo</replaceable> are:

 

413

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

 

414

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

 

415

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

 

416

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

 

417

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

 

418

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

 

419

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

 

420

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

 

421

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

 

422

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

 

423

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

 

424

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

 

425

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

 

426

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

 

427

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

 

428

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

 

429

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

 

430

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

 

431

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

 

432

        may be preserved to any new versions of this software.

363

433

      </para>

364

434

      <para>

365

435

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

393

463

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

394

464

      obscure.

395

465

    </para>

 

466

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

396

467

  </refsect1>

397

468

  

398

469

  <refsect1 id="example">

400

471

    <informalexample>

401

472

      <programlisting>

402

473

[DEFAULT]

403

 

timeout = 1h

404

 

interval = 5m

 

474

timeout = PT5M

 

475

interval = PT2M

405

476

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

406

477

 

407

478

# Client "foo"

424

495

        4T2zw4dxS5NswXWU0sVEXxjs6PYxuIiCTL7vdpx8QjBkrPWDrAbcMyBr2O

425

496

        QlnHIvPzEArRQLo=

426

497

host = foo.example.org

427

 

interval = 1m

 

498

interval = PT1M

428

499

 

429

500

# Client "bar"

430

501

[bar]

431

502

fingerprint = 3e393aeaefb84c7e89e2f547b3a107558fca3a27

432

503

secfile = /etc/mandos/bar-secret

433

 

timeout = 15m

 

504

timeout = PT15M

434

505

approved_by_default = False

435

 

approval_delay = 30s

 

506

approval_delay = PT30S

436

507

      </programlisting>

437

508

    </informalexample>

438

509

  </refsect1>

440

511

  <refsect1 id="see_also">

441

512

    <title>SEE ALSO</title>

442

513

    <para>

 

514

      <citerefentry><refentrytitle>intro</refentrytitle>

 

515

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

443

516

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

444

517

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

445

518

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

446

519

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

447

520

      <citerefentry><refentrytitle>mandos</refentrytitle>

 

521

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

 

522

      <citerefentry><refentrytitle>fping</refentrytitle>

448

523

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

449

524

    </para>

 

525

    <variablelist>

 

526

      <varlistentry>

 

527

        <term>

 

528

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

 

529

          Timestamps</citetitle>

 

530

        </term>

 

531

      <listitem>

 

532

        <para>

 

533

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

 

534

          specified in ABNF in Appendix A of RFC 3339.

 

535

        </para>

 

536

      </listitem>

 

537

      </varlistentry>

 

538

    </variablelist>

450

539

  </refsect1>

451

540

</refentry>

452

541

<!-- Local Variables: -->

• Older »

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