/mandos/release

« back to all changes in this revision

Viewing changes to mandos-clients.conf.xml

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

• reverse the comparison (383 to 237.2.202)
• stop comparing with revision 237.2.202

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

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>

 

45

      <year>2018</year>

 

46

      <year>2019</year>

37

47

      <holder>Teddy Hogeborn</holder>

38

48

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

39

49

    </copyright>

63

73

      ><refentrytitle>mandos</refentrytitle>

64

74

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

65

75

      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.

 

76

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

 

77

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

 

78

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

 

79

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

 

80

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

 

81

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

 

82

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

68

83

    </para>

69

84

    <para>

70

85

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

109

124

          <para>

110

125

            How long to wait for external approval before resorting to

111

126

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

112

 

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

 

127

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

113

128

          </para>

114

129

          <para>

115

130

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

159

174

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

160

175

          </para>

161

176

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

 

177

            This option overrides the default shell command that the

 

178

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

 

179

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

 

180

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

 

181

            client is considered up.  The command will be run using

 

182

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

168

183

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

169

184

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

170

185

            value for the checker command is <quote><literal

171

186

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

172

 

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

 

187

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

 

188

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

 

189

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

 

190

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

 

191

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

 

192

            client’s SSH key fingerprint – this is more secure against

 

193

            spoofing.

173

194

          </para>

174

195

          <para>

175

196

            In addition to normal start time expansion, this option

180

201

      </varlistentry>

181

202

      

182

203

      <varlistentry>

 

204

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

 

205

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

 

206

        <listitem>

 

207

          <para>

 

208

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

 

209

          </para>

 

210

          <para>

 

211

            Extended timeout is an added timeout that is given once

 

212

            after a password has been sent successfully to a client.

 

213

            The timeout is by default longer than the normal timeout,

 

214

            and is used for handling the extra long downtime while a

 

215

            machine is booting up.  Time to take into consideration

 

216

            when changing this value is file system checks and quota

 

217

            checks.  The default value is 15 minutes.

 

218

          </para>

 

219

          <para>

 

220

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

 

221

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

 

222

          </para>

 

223

        </listitem>

 

224

      </varlistentry>

 

225

      

 

226

      <varlistentry>

183

227

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

184

228

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

185

229

        <listitem>

189

233

          <para>

190

234

            This option sets the OpenPGP fingerprint that identifies

191

235

            the public key that clients authenticate themselves with

192

 

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

 

236

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

 

237

            but spaces or upper/lower case are not significant.

 

238

          </para>

 

239

        </listitem>

 

240

      </varlistentry>

 

241

      

 

242

      <varlistentry>

 

243

        <term><option>key_id<literal> = </literal

 

244

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

 

245

        <listitem>

 

246

          <para>

 

247

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

 

248

          </para>

 

249

          <para>

 

250

            This option sets the certificate key ID that identifies

 

251

            the public key that clients authenticate themselves with

 

252

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

193

253

            but spaces or upper/lower case are not significant.

194

254

          </para>

195

255

        </listitem>

227

287

            will wait for a checker to complete until the below

228

288

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

229

289

            time the client will be disabled, and any running checker

230

 

            killed.  The default interval is 5 minutes.

 

290

            killed.  The default interval is 2 minutes.

231

291

          </para>

232

292

          <para>

233

293

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

271

331

          <para>

272

332

            If present, this option must be set to a string of

273

333

            base64-encoded binary data.  It will be decoded and sent

274

 

            to the client matching the above

275

 

            <option>fingerprint</option>.  This should, of course, be

276

 

            OpenPGP encrypted data, decryptable only by the client.

 

334

            to the client matching the above <option>key_id</option>

 

335

            or <option>fingerprint</option>.  This should, of course,

 

336

            be OpenPGP encrypted data, decryptable only by the client.

277

337

            The program <citerefentry><refentrytitle><command

278

338

            >mandos-keygen</command></refentrytitle><manvolnum

279

339

            >8</manvolnum></citerefentry> can, using its

297

357

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

298

358

          </para>

299

359

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

 

360

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

 

361

            successful checker run, until a client is disabled and not

 

362

            allowed to get the data this server holds.  By default

 

363

            Mandos will use 5 minutes.  See also the

 

364

            <option>extended_timeout</option> option.

 

365

          </para>

 

366

          <para>

 

367

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

 

368

            3339 duration; for example

 

369

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

 

370

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

 

371

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

 

372

            RFC 3339 Appendix A for details.

 

373

          </para>

 

374

        </listitem>

 

375

      </varlistentry>

 

376

      

 

377

      <varlistentry>

 

378

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

 

379

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

 

380

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

 

381

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

 

382

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

 

383

        <listitem>

 

384

          <para>

 

385

            Whether this client should be enabled by default.  The

 

386

            default is <quote>true</quote>.

317

387

          </para>

318

388

        </listitem>

319

389

      </varlistentry>

356

426

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

357

427

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

358

428

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

 

429

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

 

430

        Mandos server.  The currently allowed values for

 

431

        <replaceable>foo</replaceable> are:

 

432

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

 

433

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

 

434

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

 

435

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

 

436

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

 

437

        <quote><literal>key_id</literal></quote>,

 

438

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

 

439

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

 

440

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

 

441

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

 

442

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

 

443

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

 

444

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

 

445

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

 

446

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

 

447

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

 

448

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

 

449

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

 

450

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

 

451

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

 

452

        may be preserved to any new versions of this software.

363

453

      </para>

364

454

      <para>

365

455

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

393

483

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

394

484

      obscure.

395

485

    </para>

 

486

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

396

487

  </refsect1>

397

488

  

398

489

  <refsect1 id="example">

400

491

    <informalexample>

401

492

      <programlisting>

402

493

[DEFAULT]

403

 

timeout = 1h

404

 

interval = 5m

 

494

timeout = PT5M

 

495

interval = PT2M

405

496

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

406

497

 

407

498

# Client "foo"

408

499

[foo]

 

500

key_id = 788cd77115cd0bb7b2d5e0ae8496f6b48149d5e712c652076b1fd2d957ef7c1f

409

501

fingerprint =  7788 2722 5BA7 DE53 9C5A  7CFA 59CF F7CD BD9A 5920

410

502

secret =

411

503

        hQIOA6QdEjBs2L/HEAf/TCyrDe5Xnm9esa+Pb/vWF9CUqfn4srzVgSu234

424

516

        4T2zw4dxS5NswXWU0sVEXxjs6PYxuIiCTL7vdpx8QjBkrPWDrAbcMyBr2O

425

517

        QlnHIvPzEArRQLo=

426

518

host = foo.example.org

427

 

interval = 1m

 

519

interval = PT1M

428

520

 

429

521

# Client "bar"

430

522

[bar]

 

523

key_id = F90C7A81D72D1EA69A51031A91FF8885F36C8B46D155C8C58709A4C99AE9E361

431

524

fingerprint = 3e393aeaefb84c7e89e2f547b3a107558fca3a27

432

525

secfile = /etc/mandos/bar-secret

433

 

timeout = 15m

 

526

timeout = PT15M

434

527

approved_by_default = False

435

 

approval_delay = 30s

 

528

approval_delay = PT30S

436

529

      </programlisting>

437

530

    </informalexample>

438

531

  </refsect1>

440

533

  <refsect1 id="see_also">

441

534

    <title>SEE ALSO</title>

442

535

    <para>

 

536

      <citerefentry><refentrytitle>intro</refentrytitle>

 

537

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

443

538

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

444

539

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

445

540

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

446

541

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

447

542

      <citerefentry><refentrytitle>mandos</refentrytitle>

 

543

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

 

544

      <citerefentry><refentrytitle>fping</refentrytitle>

448

545

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

449

546

    </para>

 

547

    <variablelist>

 

548

      <varlistentry>

 

549

        <term>

 

550

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

 

551

          Timestamps</citetitle>

 

552

        </term>

 

553

      <listitem>

 

554

        <para>

 

555

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

 

556

          specified in ABNF in Appendix A of RFC 3339.

 

557

        </para>

 

558

      </listitem>

 

559

      </varlistentry>

 

560

    </variablelist>

450

561

  </refsect1>

451

562

</refentry>

452

563

<!-- Local Variables: -->

• Older »

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