/mandos/trunk : revision 109

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-27 01:18:25 UTC
Revision ID: teddy@fukt.bsnet.se-20080827011825-ka3ni6xvy2ehi1y8

* .bzrignore: New.

* clients.conf ([foo]): Remove Radix-64 checksum.

* mandos (AvahiService.rename, server_state_changed,
          entry_group_state_changed): Make Avahi log messages more
                                      clear that they are about
                                      Zeroconf.
  (fingerprint): Use plain "0" instead of "ctypes.c_uint(0)".

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

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

<title>&CONFNAME;</title>

<productname>&CONFNAME;</productname>

<productnumber>&VERSION;</productnumber>

<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

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

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

100

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

101

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

102

leading whitespace is removed from values. Values can contain

103

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

104

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

105

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

106

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

107

comments.

108

</para>

109

</refsect1>

110

111

112

<title>OPTIONS</title>

113

<para>

114

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

115

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

116

</para>

117

<para>

118

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

119

</para>

120

121

122

123

124

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

125

126

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

127

>TIME</replaceable>

128

</synopsis>

129

<para>

130

The timeout is how long the server will wait for a

131

successful checker run until a client is considered

132

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

133

holds. By default Mandos will use 1 hour.

134

</para>

135

<para>

136

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

137

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

138

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

139

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

140

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

141

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

142

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

143

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

144

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

145

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

146

of five minutes and thirty seconds.

147

</para>

148

</listitem>

149

</varlistentry>

150

151

152

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

153

154

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

155

>TIME</replaceable>

156

</synopsis>

157

<para>

158

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

159

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

160

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

161

will wait for a checker to complete until the above

162

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

163

time the client will be marked invalid, and any running

164

checker killed. The default interval is 5 minutes.

165

</para>

166

<para>

167

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

168

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

169

</para>

170

</listitem>

171

</varlistentry>

172

173

174

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

175

176

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

177

>COMMAND</replaceable>

178

</synopsis>

179

<para>

180

This option allows you to override the default shell

181

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

182

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

183

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

184

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

185

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

186

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

187

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

188

value for the checker command is <quote><literal

189

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

190

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

191

</para>

192

<para>

193

In addition to normal start time expansion, this option

194

will also be subject to runtime expansion; see <xref

195

linkend="expansion"/>.

196

</para>

197

</listitem>

198

</varlistentry>

199

200

201

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

202

203

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

204

>HEXSTRING</replaceable>

205

</synopsis>

206

<para>

207

This option sets the OpenPGP fingerprint that identifies

208

the public key that clients authenticate themselves with

209

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

210

but spaces or upper/lower case are not significant.

211

</para>

212

</listitem>

213

</varlistentry>

214

215

216

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

217

218

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

219

>BASE64_ENCODED_DATA</replaceable>

220

</synopsis>

221

<para>

222

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

223

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

224

to the client matching the above

225

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

226

OpenPGP encrypted data, decryptable only by the client.

227

The program <citerefentry><refentrytitle><command

228

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

229

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

230

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

231

this, if desired.

232

</para>

233

<para>

234

Note: this value of this option will probably be very

235

long. A useful feature to avoid having unreadably-long

236

lines is that a line beginning with white space adds to

237

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

238

</para>

239

<para>

240

If this option is not specified, the <option

241

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

242

<emphasis>must</emphasis> be present.

243

</para>

244

</listitem>

245

</varlistentry>

246

247

248

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

249

250

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

251

>FILENAME</replaceable>

252

</synopsis>

253

<para>

254

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

255

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

256

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

257

sent to clients verbatim.

258

</para>

259

<para>

260

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

261

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

262

</para>

263

</listitem>

264

</varlistentry>

265

266

267

268

269

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

270

>STRING</replaceable>

271

</synopsis>

272

<para>

273

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

274

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

275

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

276

</para>

277

</listitem>

278

</varlistentry>

279

280

</variablelist>

281

</refsect1>

282

283

284

<title>EXPANSION</title>

285

<para>

286

There are two forms of expansion: Start time expansion and

287

runtime expansion.

288

</para>

289

290

<title>START TIME EXPANSION</title>

291

<para>

292

Any string in an option value of the form

293

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

294

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

295

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

296

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

297

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

298

file is read.

299

</para>

300

<para>

301

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

302

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

303

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

304

entered.

305

</para>

306

</refsect2>

307

308

<title>RUNTIME EXPANSION</title>

309

<para>

310

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

311

option.

312

</para>

313

<para>

314

Any string in an option value of the form

315

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

316

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

317

<varname>foo</varname> of the internal

318

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

319

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

320

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

321

versions of this software.

322

</para>

323

<para>

324

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

325

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

326

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

327

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

328

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

329

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

330

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

331

</para>

332

</refsect2>

333

334

</refsect1>

335

336

337

<title>FILES</title>

338

<para>

339

The file described here is &CONFPATH;

340

</para>

341

</refsect1>

342

343

344

345

<para>

346

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

347

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

348

</para>

349

<para>

350

The difference between

351

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

352

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

353

obscure.

354

</para>

355

</refsect1>

356

357

358

<title>EXAMPLE</title>

359

360

361

[DEFAULT]

362

timeout = 1h

363

interval = 5m

364

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

365

366

# Client "foo"

367

[foo]

368

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

369

secret =

370

hQIOA6QdEjBs2L/HEAf/TCyrDe5Xnm9esa+Pb/vWF9CUqfn4srzVgSu234

371

REJMVv7lBSrPE2132Lmd2gqF1HeLKDJRSVxJpt6xoWOChGHg+TMyXDxK+N

372

Xl89vGvdU1XfhKkVm9MDLOgT5ECDPysDGHFPDhqHOSu3Kaw2DWMV/iH9vz

373

3Z20erVNbdcvyBnuojcoWO/6yfB5EQO0BXp7kcyy00USA3CjD5FGZdoQGI

374

Tb8A/ar0tVA5crSQmaSotm6KmNLhrFnZ5BxX+TiE+eTUTqSloWRY6VAvqW

375

QHC7OASxK5E6RXPBuFH5IohUA2Qbk5AHt99pYvsIPX88j2rWauOokoiKZo

376

t/9leJ8VxO5l3wf/U64IH8bkPIoWmWZfd/nqh4uwGNbCgKMyT+AnvH7kMJ

377

3i7DivfWl2mKLV0PyPHUNva0VQxX6yYjcOhj1R6fCr/at8/NSLe2OhLchz

378

dC+Ls9h+kvJXgF8Sisv+Wk/1RadPLFmraRlqvJwt6Ww21LpiXqXHV2mIgq

379

WnR98YgSvUi3TJHrUQiNc9YyBzuRo0AjgG2C9qiE3FM+Y28+iQ/sR3+bFs

380

zYuZKVTObqiIslwXu7imO0cvvFRgJF/6u3HNFQ4LUTGhiM3FQmC6NNlF3/

381

vJM2hwRDMcJqDd54Twx90Wh+tYz0z7QMsK4ANXWHHWHR0JchnLWmenzbtW

382

5MHdW9AYsNJZAQSOpirE4Xi31CSlWAi9KV+cUCmWF5zOFy1x23P6PjdaRm

383

4T2zw4dxS5NswXWU0sVEXxjs6PYxuIiCTL7vdpx8QjBkrPWDrAbcMyBr2O

384

QlnHIvPzEArRQLo=

385

host = foo.example.org

386

interval = 1m

387

388

# Client "bar"

389

[bar]

390

fingerprint = 3e393aeaefb84c7e89e2f547b3a107558fca3a27

391

secfile = /etc/mandos/bar-secret

392

timeout = 15m

393

394

</programlisting>

395

</informalexample>

396

</refsect1>

397

398

399

400

<para>

401

402

<refentrytitle>mandos</refentrytitle>

403

404

<refentrytitle>mandos-keygen</refentrytitle>

405

406

<refentrytitle>mandos.conf</refentrytitle>

407

408

</para>

409

</refsect1>

410

</refentry>

Older »