/mandos/release

« back to all changes in this revision

Viewing changes to mandos-clients.conf.xml

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

• reverse the comparison (180 to 237.7.177)
• stop comparing with revision 237.7.177

Show diffs side-by-side

added

removed

mandos-clients.conf.xml

1

1

<?xml version="1.0" encoding="UTF-8"?>

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

<!ENTITY VERSION "1.0">

4

5

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

5

6

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

6

 

<!ENTITY TIMESTAMP "2013-10-15">

7

 

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

8

 

%common;

 

7

<!ENTITY TIMESTAMP "2008-09-04">

9

8

]>

10

9

 

11

10

<refentry xmlns:xi="http://www.w3.org/2001/XInclude">

13

12

    <title>Mandos Manual</title>

14

13

    <!-- NWalsh’s docbook scripts use this to generate the footer: -->

15

14

    <productname>Mandos</productname>

16

 

    <productnumber>&version;</productnumber>

 

15

    <productnumber>&VERSION;</productnumber>

17

16

    <date>&TIMESTAMP;</date>

18

17

    <authorgroup>

19

18

      <author>

20

19

        <firstname>Björn</firstname>

21

20

        <surname>Påhlsson</surname>

22

21

        <address>

23

 

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

 

22

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

24

23

        </address>

25

24

      </author>

26

25

      <author>

27

26

        <firstname>Teddy</firstname>

28

27

        <surname>Hogeborn</surname>

29

28

        <address>

30

 

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

 

29

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

31

30

        </address>

32

31

      </author>

33

32

    </authorgroup>

34

33

    <copyright>

35

34

      <year>2008</year>

36

 

      <year>2009</year>

37

 

      <year>2010</year>

38

 

      <year>2011</year>

39

 

      <year>2012</year>

40

35

      <holder>Teddy Hogeborn</holder>

41

36

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

42

37

    </copyright>

43

38

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

44

39

  </refentryinfo>

45

 

  

 

40

 

46

41

  <refmeta>

47

42

    <refentrytitle>&CONFNAME;</refentrytitle>

48

43

    <manvolnum>5</manvolnum>

54

49

      Configuration file for the Mandos server

55

50

    </refpurpose>

56

51

  </refnamediv>

57

 

  

 

52

 

58

53

  <refsynopsisdiv>

59

54

    <synopsis>&CONFPATH;</synopsis>

60

55

  </refsynopsisdiv>

61

 

  

 

56

 

62

57

  <refsect1 id="description">

63

58

    <title>DESCRIPTION</title>

64

59

    <para>

66

61

      ><refentrytitle>mandos</refentrytitle>

67

62

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

68

63

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

69

 

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

70

 

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

71

 

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

72

 

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

73

 

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

74

 

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

75

 

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

 

64

      the service.  All clients listed will be regarded as valid, even

 

65

      if a client was declared invalid in a previous run of the

 

66

      server.

76

67

    </para>

77

68

    <para>

78

69

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

104

95

    <para>

105

96

      Unknown options are ignored.  The used options are as follows:

106

97

    </para>

107

 

    

 

98

 

108

99

    <variablelist>

109

 

      

110

 

      <varlistentry>

111

 

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

112

 

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

113

 

        <listitem>

114

 

          <para>

115

 

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

116

 

          </para>

117

 

          <para>

118

 

            How long to wait for external approval before resorting to

119

 

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

120

 

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

121

 

          </para>

122

 

          <para>

123

 

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

124

 

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

125

 

          </para>

126

 

        </listitem>

127

 

      </varlistentry>

128

 

      

129

 

      <varlistentry>

130

 

        <term><option>approval_duration<literal> = </literal

131

 

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

132

 

        <listitem>

133

 

          <para>

134

 

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

135

 

          </para>

136

 

          <para>

137

 

            How long an external approval lasts.  The default is 1

138

 

            second.

139

 

          </para>

140

 

          <para>

141

 

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

142

 

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

143

 

          </para>

144

 

        </listitem>

145

 

      </varlistentry>

146

 

      

147

 

      <varlistentry>

148

 

        <term><option>approved_by_default<literal> = </literal

149

 

          >{ <literal >1</literal> | <literal>yes</literal> | <literal

150

 

          >true</literal> | <literal>on</literal> | <literal

151

 

          >0</literal> | <literal>no</literal> | <literal

152

 

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

153

 

        <listitem>

154

 

          <para>

155

 

            Whether to approve a client by default after

156

 

            the <option>approval_delay</option>.  The default

157

 

            is <quote>True</quote>.

158

 

          </para>

159

 

        </listitem>

160

 

      </varlistentry>

161

 

      

 

100

 

 

101

      <varlistentry>

 

102

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

 

103

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

 

104

        <listitem>

 

105

          <para>

 

106

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

 

107

          </para>

 

108

          <para>

 

109

            The timeout is how long the server will wait for a

 

110

            successful checker run until a client is considered

 

111

            invalid - that is, ineligible to get the data this server

 

112

            holds.  By default Mandos will use 1 hour.

 

113

          </para>

 

114

          <para>

 

115

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

 

116

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

 

117

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

 

118

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

 

119

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

 

120

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

 

121

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

 

122

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

 

123

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

 

124

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

 

125

            of five minutes and thirty seconds.

 

126

          </para>

 

127

        </listitem>

 

128

      </varlistentry>

 

129

 

 

130

      <varlistentry>

 

131

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

 

132

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

 

133

        <listitem>

 

134

          <para>

 

135

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

 

136

          </para>

 

137

          <para>

 

138

            How often to run the checker to confirm that a client is

 

139

            still up.  <emphasis>Note:</emphasis> a new checker will

 

140

            not be started if an old one is still running.  The server

 

141

            will wait for a checker to complete until the above

 

142

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

 

143

            time the client will be marked invalid, and any running

 

144

            checker killed.  The default interval is 5 minutes.

 

145

          </para>

 

146

          <para>

 

147

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

 

148

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

 

149

          </para>

 

150

        </listitem>

 

151

      </varlistentry>

 

152

 

162

153

      <varlistentry>

163

154

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

164

155

        >COMMAND</replaceable></option></term>

167

158

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

168

159

          </para>

169

160

          <para>

170

 

            This option overrides the default shell command that the

171

 

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

172

 

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

173

 

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

174

 

            client is considered up.  The command will be run using

175

 

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

 

161

            This option allows you to override the default shell

 

162

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

 

163

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

 

164

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

 

165

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

 

166

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

176

167

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

177

168

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

178

169

            value for the checker command is <quote><literal

179

170

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

180

 

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

 

171

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

181

172

          </para>

182

173

          <para>

183

174

            In addition to normal start time expansion, this option

188

179

      </varlistentry>

189

180

      

190

181

      <varlistentry>

191

 

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

192

 

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

193

 

        <listitem>

194

 

          <para>

195

 

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

196

 

          </para>

197

 

          <para>

198

 

            Extended timeout is an added timeout that is given once

199

 

            after a password has been sent successfully to a client.

200

 

            The timeout is by default longer than the normal timeout,

201

 

            and is used for handling the extra long downtime while a

202

 

            machine is booting up.  Time to take into consideration

203

 

            when changing this value is file system checks and quota

204

 

            checks.  The default value is 15 minutes.

205

 

          </para>

206

 

          <para>

207

 

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

208

 

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

209

 

          </para>

210

 

        </listitem>

211

 

      </varlistentry>

212

 

      

213

 

      <varlistentry>

214

182

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

215

183

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

216

184

        <listitem>

227

195

      </varlistentry>

228

196

      

229

197

      <varlistentry>

230

 

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

231

 

        >STRING</replaceable></option></term>

232

 

        <listitem>

233

 

          <para>

234

 

            This option is <emphasis>optional</emphasis>, but highly

235

 

            <emphasis>recommended</emphasis> unless the

236

 

            <option>checker</option> option is modified to a

237

 

            non-standard value without <quote>%%(host)s</quote> in it.

238

 

          </para>

239

 

          <para>

240

 

            Host name for this client.  This is not used by the server

241

 

            directly, but can be, and is by default, used by the

242

 

            checker.  See the <option>checker</option> option.

243

 

          </para>

244

 

        </listitem>

245

 

      </varlistentry>

246

 

      

247

 

      <varlistentry>

248

 

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

249

 

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

250

 

        <listitem>

251

 

          <para>

252

 

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

253

 

          </para>

254

 

          <para>

255

 

            How often to run the checker to confirm that a client is

256

 

            still up.  <emphasis>Note:</emphasis> a new checker will

257

 

            not be started if an old one is still running.  The server

258

 

            will wait for a checker to complete until the below

259

 

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

260

 

            time the client will be disabled, and any running checker

261

 

            killed.  The default interval is 2 minutes.

262

 

          </para>

263

 

          <para>

264

 

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

265

 

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

266

 

          </para>

267

 

        </listitem>

268

 

      </varlistentry>

269

 

      

270

 

      <varlistentry>

271

 

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

272

 

        >FILENAME</replaceable></option></term>

273

 

        <listitem>

274

 

          <para>

275

 

            This option is only used if <option>secret</option> is not

276

 

            specified, in which case this option is

277

 

            <emphasis>required</emphasis>.

278

 

          </para>

279

 

          <para>

280

 

            Similar to the <option>secret</option>, except the secret

281

 

            data is in an external file.  The contents of the file

282

 

            should <emphasis>not</emphasis> be base64-encoded, but

283

 

            will be sent to clients verbatim.

284

 

          </para>

285

 

          <para>

286

 

            File names of the form <filename>~user/foo/bar</filename>

287

 

            and <filename>$<envar>ENVVAR</envar>/foo/bar</filename>

288

 

            are supported.

289

 

          </para>

290

 

        </listitem>

291

 

      </varlistentry>

292

 

      

293

 

      <varlistentry>

294

198

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

295

199

        >BASE64_ENCODED_DATA</replaceable></option></term>

296

200

        <listitem>

319

223

          </para>

320

224

        </listitem>

321

225

      </varlistentry>

322

 

      

 

226

 

323

227

      <varlistentry>

324

 

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

325

 

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

 

228

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

 

229

        >FILENAME</replaceable></option></term>

326

230

        <listitem>

327

231

          <para>

328

 

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

329

 

          </para>

330

 

          <para>

331

 

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

332

 

            successful checker run, until a client is disabled and not

333

 

            allowed to get the data this server holds.  By default

334

 

            Mandos will use 5 minutes.  See also the

335

 

            <option>extended_timeout</option> option.

336

 

          </para>

337

 

          <para>

338

 

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

339

 

            3339 duration; for example

340

 

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

341

 

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

342

 

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

343

 

            RFC 3339 Appendix A for details.

 

232

            This option is only used if <option>secret</option> is not

 

233

            specified, in which case this option is

 

234

            <emphasis>required</emphasis>.

 

235

          </para>

 

236

          <para>

 

237

            Similar to the <option>secret</option>, except the secret

 

238

            data is in an external file.  The contents of the file

 

239

            should <emphasis>not</emphasis> be base64-encoded, but

 

240

            will be sent to clients verbatim.

344

241

          </para>

345

242

        </listitem>

346

243

      </varlistentry>

347

 

      

 

244

 

348

245

      <varlistentry>

349

 

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

350

 

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

351

 

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

352

 

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

353

 

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

 

246

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

 

247

        >STRING</replaceable></option></term>

354

248

        <listitem>

355

249

          <para>

356

 

            Whether this client should be enabled by default.  The

357

 

            default is <quote>true</quote>.

 

250

            This option is <emphasis>optional</emphasis>, but highly

 

251

            <emphasis>recommended</emphasis> unless the

 

252

            <option>checker</option> option is modified to a

 

253

            non-standard value without <quote>%(host)s</quote> in it.

 

254

          </para>

 

255

          <para>

 

256

            Host name for this client.  This is not used by the server

 

257

            directly, but can be, and is by default, used by the

 

258

            checker.  See the <option>checker</option> option.

358

259

          </para>

359

260

        </listitem>

360

261

      </varlistentry>

397

298

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

398

299

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

399

300

        <varname>foo</varname> of the internal

400

 

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

401

 

        Mandos server.  The currently allowed values for

402

 

        <replaceable>foo</replaceable> are:

403

 

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

404

 

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

405

 

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

406

 

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

407

 

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

408

 

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

409

 

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

410

 

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

411

 

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

412

 

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

413

 

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

414

 

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

415

 

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

416

 

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

417

 

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

418

 

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

419

 

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

420

 

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

421

 

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

422

 

        may be preserved to any new versions of this software.

 

301

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

 

302

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

 

303

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

 

304

        versions of this software.

423

305

      </para>

424

306

      <para>

425

307

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

431

313

        mode is needed to expose an error of this kind.

432

314

      </para>

433

315

    </refsect2>

434

 

    

 

316

 

435

317

  </refsect1>

436

318

  

437

319

  <refsect1 id="files">

460

342

    <informalexample>

461

343

      <programlisting>

462

344

[DEFAULT]

463

 

timeout = PT5M

464

 

interval = PT2M

465

 

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

 

345

timeout = 1h

 

346

interval = 5m

 

347

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

466

348

 

467

349

# Client "foo"

468

350

[foo]

484

366

        4T2zw4dxS5NswXWU0sVEXxjs6PYxuIiCTL7vdpx8QjBkrPWDrAbcMyBr2O

485

367

        QlnHIvPzEArRQLo=

486

368

host = foo.example.org

487

 

interval = PT1M

 

369

interval = 1m

488

370

 

489

371

# Client "bar"

490

372

[bar]

491

373

fingerprint = 3e393aeaefb84c7e89e2f547b3a107558fca3a27

492

374

secfile = /etc/mandos/bar-secret

493

 

timeout = PT15M

494

 

approved_by_default = False

495

 

approval_delay = PT30S

 

375

timeout = 15m

 

376

 

496

377

      </programlisting>

497

378

    </informalexample>

498

379

  </refsect1>

500

381

  <refsect1 id="see_also">

501

382

    <title>SEE ALSO</title>

502

383

    <para>

503

 

      <citerefentry><refentrytitle>intro</refentrytitle>

504

 

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

505

384

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

506

385

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

507

386

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

508

387

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

509

388

      <citerefentry><refentrytitle>mandos</refentrytitle>

510

 

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

511

 

      <citerefentry><refentrytitle>fping</refentrytitle>

512

389

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

513

390

    </para>

514

 

    <variablelist>

515

 

      <varlistentry>

516

 

        <term>

517

 

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

518

 

          Timestamps</citetitle>

519

 

        </term>

520

 

      <listitem>

521

 

        <para>

522

 

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

523

 

          specified in ABNF in Appendix A of RFC 3339.

524

 

        </para>

525

 

      </listitem>

526

 

      </varlistentry>

527

 

    </variablelist>

528

391

  </refsect1>

529

392

</refentry>

530

393

<!-- Local Variables: -->

• Older »

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