/mandos/trunk : revision 118

To get this branch, use:

bzr branch
http://bzr.recompile.se/loggerhead/mandos/trunk

« back to all changes in this revision

Viewing changes to mandos-clients.conf.xml

Committer: Teddy Hogeborn
Date: 2008-08-30 17:16:33 UTC
Revision ID: teddy@fukt.bsnet.se-20080830171633-rjyuhsemikw6lg2w

* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
options.
* plugins.d/password-request.xml (SYNOPSIS): - '' -

* mandos-clients.conf.xml: Removed extra white space.
* plugin-runner.xml: - '' -
* plugins.d/password-prompt.xml: - '' -
* mandos-keygen.xml: - '' -
* plugins.d/password-request.xml: - '' -

files added:
.bzrignore

COPYING

initramfs-tools-hook

initramfs-tools-hook-conf

initramfs-tools-script

mandos-clients.conf.xml

mandos-keygen

mandos-keygen.xml

mandos-options.xml

mandos.conf

mandos.conf.xml

mandos.xml

overview.xml

plugin-runner.xml

plugins.d/password-prompt.xml

plugins.d/password-request.xml

plugins.d/usplash

files removed:
ca.pem

cert.pem

client-cert.pem

client-key.pem

crl.pem

key.pem

plugins.d/Makefile

files renamed:
mandos-clients.conf => clients.conf

server.py => mandos

plugbasedclient.c => plugin-runner.c

plugins.d/passprompt.c => plugins.d/password-prompt.c

plugins.d/mandosclient.c => plugins.d/password-request.c

files modified:
Makefile

TODO

Show diffs side-by-side

added added

removed removed

mandos-clients.conf.xml

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

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

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

<!ENTITY VERSION "1.0">

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

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

<!ENTITY TIMESTAMP "2008-08-30">

<title>Mandos Manual</title>

<productname>Mandos</productname>

<productnumber>&VERSION;</productnumber>

<date>&TIMESTAMP;</date>

<firstname>Björn</firstname>

<surname>Påhlsson</surname>

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

</address>

</author>

<firstname>Teddy</firstname>

<surname>Hogeborn</surname>

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

</address>

</author>

</authorgroup>

<holder>Teddy Hogeborn</holder>

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

</copyright>

<para>

This manual page is free software: you can redistribute it

and/or modify it under the terms of the GNU General Public

License as published by the Free Software Foundation,

either version 3 of the License, or (at your option) any

later version.

</para>

<para>

This manual page is distributed in the hope that it will

be useful, but WITHOUT ANY WARRANTY; without even the

implied warranty of MERCHANTABILITY or FITNESS FOR A

PARTICULAR PURPOSE. See the GNU General Public License

for more details.

</para>

<para>

You should have received a copy of the GNU General Public

License along with this program; If not, see

<ulink url="http://www.gnu.org/licenses/"/>.

</para>

</legalnotice>

</refentryinfo>

<refentrytitle>&CONFNAME;</refentrytitle>

</refmeta>

<refname><filename>&CONFNAME;</filename></refname>

Configuration file for the Mandos server

</refpurpose>

</refnamediv>

&CONFPATH;

</synopsis>

</refsynopsisdiv>

<title>DESCRIPTION</title>

<para>

The file &CONFPATH; is a configuration file for <citerefentry

><refentrytitle>mandos</refentrytitle>

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

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

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

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

server.

</para>

<para>

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

header</replaceable>]</literal> which is either

<literal>[DEFAULT]</literal> or <literal>[<replaceable>client

name</replaceable>]</literal>. The <replaceable>client

name</replaceable> can be anything, and is not tied to a host

name. Following the section header is any number of

<quote><varname><replaceable>option</replaceable

100

></varname>=<replaceable>value</replaceable></quote> entries,

101

with continuations in the style of RFC 822. <quote><varname

102

><replaceable>option</replaceable></varname>: <replaceable

103

>value</replaceable></quote> is also accepted. Note that

104

leading whitespace is removed from values. Values can contain

105

format strings which refer to other values in the same section,

106

or values in the <quote>DEFAULT</quote> section (see <xref

107

linkend="expansion"/>). Lines beginning with <quote>#</quote>

108

or <quote>;</quote> are ignored and may be used to provide

109

comments.

110

</para>

111

</refsect1>

112

113

114

<title>OPTIONS</title>

115

<para>

116

<emphasis>Note:</emphasis> all option values are subject to

117

start time expansion, see <xref linkend="expansion"/>.

118

</para>

119

<para>

120

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

121

</para>

122

123

124

125

126

<term><literal><varname>timeout</varname></literal></term>

127

128

<synopsis><literal>timeout = </literal><replaceable

129

>TIME</replaceable>

130

</synopsis>

131

<para>

132

The timeout is how long the server will wait for a

133

successful checker run until a client is considered

134

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

135

holds. By default Mandos will use 1 hour.

136

</para>

137

<para>

138

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

139

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

140

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

141

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

142

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

143

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

144

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

145

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

146

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

147

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

148

of five minutes and thirty seconds.

149

</para>

150

</listitem>

151

</varlistentry>

152

153

154

<term><literal><varname>interval</varname></literal></term>

155

156

<synopsis><literal>interval = </literal><replaceable

157

>TIME</replaceable>

158

</synopsis>

159

<para>

160

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

161

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

162

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

163

will wait for a checker to complete until the above

164

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

165

time the client will be marked invalid, and any running

166

checker killed. The default interval is 5 minutes.

167

</para>

168

<para>

169

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

170

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

171

</para>

172

</listitem>

173

</varlistentry>

174

175

176

<term><literal>checker</literal></term>

177

178

<synopsis><literal>checker = </literal><replaceable

179

>COMMAND</replaceable>

180

</synopsis>

181

<para>

182

This option allows you to override the default shell

183

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

184

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

185

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

186

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

187

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

188

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

189

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

190

value for the checker command is <quote><literal

191

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

192

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

193

</para>

194

<para>

195

In addition to normal start time expansion, this option

196

will also be subject to runtime expansion; see <xref

197

linkend="expansion"/>.

198

</para>

199

</listitem>

200

</varlistentry>

201

202

203

<term><literal>fingerprint</literal></term>

204

205

<synopsis><literal>fingerprint = </literal><replaceable

206

>HEXSTRING</replaceable>

207

</synopsis>

208

<para>

209

This option sets the OpenPGP fingerprint that identifies

210

the public key that clients authenticate themselves with

211

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

212

but spaces or upper/lower case are not significant.

213

</para>

214

</listitem>

215

</varlistentry>

216

217

218

<term><literal>secret</literal></term>

219

220

<synopsis><literal>secret = </literal><replaceable

221

>BASE64_ENCODED_DATA</replaceable>

222

</synopsis>

223

<para>

224

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

225

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

226

to the client matching the above

227

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

228

OpenPGP encrypted data, decryptable only by the client.

229

The program <citerefentry><refentrytitle><command

230

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

231

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

232

<option>--password</option> option, be used to generate

233

this, if desired.

234

</para>

235

<para>

236

Note: this value of this option will probably be very

237

long. A useful feature to avoid having unreadably-long

238

lines is that a line beginning with white space adds to

239

the value of the previous line, RFC 822-style.

240

</para>

241

<para>

242

If this option is not specified, the <option

243

>secfile</option> option is used instead, but one of them

244

<emphasis>must</emphasis> be present.

245

</para>

246

</listitem>

247

</varlistentry>

248

249

250

<term><literal>secfile</literal></term>

251

252

<synopsis><literal>secfile = </literal><replaceable

253

>FILENAME</replaceable>

254

</synopsis>

255

<para>

256

The same as <option>secret</option>, but the secret data

257

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

258

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

259

sent to clients verbatim.

260

</para>

261

<para>

262

This option is only used, and <emphasis>must</emphasis> be

263

present, if <option>secret</option> is not specified.

264

</para>

265

</listitem>

266

</varlistentry>

267

268

269

270

271

<synopsis><literal>host = </literal><replaceable

272

>STRING</replaceable>

273

</synopsis>

274

<para>

275

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

276

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

277

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

278

</para>

279

</listitem>

280

</varlistentry>

281

282

</variablelist>

283

</refsect1>

284

285

286

<title>EXPANSION</title>

287

<para>

288

There are two forms of expansion: Start time expansion and

289

runtime expansion.

290

</para>

291

292

<title>START TIME EXPANSION</title>

293

<para>

294

Any string in an option value of the form

295

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

296

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

297

<varname>foo</varname> either in the same section, or, if it

298

does not exist there, the <literal>[DEFAULT]</literal>

299

section. This is done at start time, when the configuration

300

file is read.

301

</para>

302

<para>

303

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

304

percent character (<quote>%</quote>) in an option value, two

305

percent characters in a row (<quote>%%</quote>) must be

306

entered.

307

</para>

308

</refsect2>

309

310

<title>RUNTIME EXPANSION</title>

311

<para>

312

This is currently only done for the <varname>checker</varname>

313

option.

314

</para>

315

<para>

316

Any string in an option value of the form

317

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

318

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

319

<varname>foo</varname> of the internal

320

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

321

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

322

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

323

versions of this software.

324

</para>

325

<para>

326

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

327

percent character (<quote>%</quote>) in a

328

<varname>checker</varname> option, <emphasis>four</emphasis>

329

percent characters in a row (<quote>%%%%</quote>) must be

330

entered. Also, a bad format here will lead to an immediate

331

but <emphasis>silent</emphasis> run-time fatal exit; debug

332

mode is needed to track down an error of this kind.

333

</para>

334

</refsect2>

335

336

</refsect1>

337

338

339

<title>FILES</title>

340

<para>

341

The file described here is &CONFPATH;

342

</para>

343

</refsect1>

344

345

346

347

<para>

348

The format for specifying times for <varname>timeout</varname>

349

and <varname>interval</varname> is not very good.

350

</para>

351

<para>

352

The difference between

353

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

354

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

355

obscure.

356

</para>

357

</refsect1>

358

359

360

<title>EXAMPLE</title>

361

362

363

[DEFAULT]

364

timeout = 1h

365

interval = 5m

366

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

367

368

# Client "foo"

369

[foo]

370

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

371

secret =

372

hQIOA6QdEjBs2L/HEAf/TCyrDe5Xnm9esa+Pb/vWF9CUqfn4srzVgSu234

373

REJMVv7lBSrPE2132Lmd2gqF1HeLKDJRSVxJpt6xoWOChGHg+TMyXDxK+N

374

Xl89vGvdU1XfhKkVm9MDLOgT5ECDPysDGHFPDhqHOSu3Kaw2DWMV/iH9vz

375

3Z20erVNbdcvyBnuojcoWO/6yfB5EQO0BXp7kcyy00USA3CjD5FGZdoQGI

376

Tb8A/ar0tVA5crSQmaSotm6KmNLhrFnZ5BxX+TiE+eTUTqSloWRY6VAvqW

377

QHC7OASxK5E6RXPBuFH5IohUA2Qbk5AHt99pYvsIPX88j2rWauOokoiKZo

378

t/9leJ8VxO5l3wf/U64IH8bkPIoWmWZfd/nqh4uwGNbCgKMyT+AnvH7kMJ

379

3i7DivfWl2mKLV0PyPHUNva0VQxX6yYjcOhj1R6fCr/at8/NSLe2OhLchz

380

dC+Ls9h+kvJXgF8Sisv+Wk/1RadPLFmraRlqvJwt6Ww21LpiXqXHV2mIgq

381

WnR98YgSvUi3TJHrUQiNc9YyBzuRo0AjgG2C9qiE3FM+Y28+iQ/sR3+bFs

382

zYuZKVTObqiIslwXu7imO0cvvFRgJF/6u3HNFQ4LUTGhiM3FQmC6NNlF3/

383

vJM2hwRDMcJqDd54Twx90Wh+tYz0z7QMsK4ANXWHHWHR0JchnLWmenzbtW

384

5MHdW9AYsNJZAQSOpirE4Xi31CSlWAi9KV+cUCmWF5zOFy1x23P6PjdaRm

385

4T2zw4dxS5NswXWU0sVEXxjs6PYxuIiCTL7vdpx8QjBkrPWDrAbcMyBr2O

386

QlnHIvPzEArRQLo=

387

host = foo.example.org

388

interval = 1m

389

390

# Client "bar"

391

[bar]

392

fingerprint = 3e393aeaefb84c7e89e2f547b3a107558fca3a27

393

secfile = /etc/mandos/bar-secret

394

timeout = 15m

395

396

</programlisting>

397

</informalexample>

398

</refsect1>

399

400

401

402

<para>

403

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

404

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

405

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

406

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

407

<citerefentry><refentrytitle>mandos</refentrytitle>

408

409

</para>

410

</refsect1>

411

</refentry>

412

413

414

415

416

Older »