/mandos/trunk : revision 24.1.168

1

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

2

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

3

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

4

<!ENTITY COMMANDNAME "plymouth">

5

<!ENTITY TIMESTAMP "2010-09-26">

6

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

7

%common;

8

]>

9

10

11

12

<title>Mandos Manual</title>

13

14

<productname>Mandos</productname>

15

<productnumber>&version;</productnumber>

16

<date>&TIMESTAMP;</date>

17

18

19

<firstname>Björn</firstname>

20

<surname>Påhlsson</surname>

21

22

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

23

</address>

24

</author>

25

26

<firstname>Teddy</firstname>

27

<surname>Hogeborn</surname>

28

29

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

30

</address>

31

</author>

32

</authorgroup>

33

34

35

<holder>Teddy Hogeborn</holder>

36

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

37

</copyright>

38

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

39

</refentryinfo>

40

41

42

<refentrytitle>&COMMANDNAME;</refentrytitle>

43

<manvolnum>8mandos</manvolnum>

44

</refmeta>

45

46

47

<refname><command>&COMMANDNAME;</command></refname>

48

<refpurpose>Mandos plugin to use plymouth to get a

49

password.</refpurpose>

50

</refnamediv>

51

52

53

54

<command>&COMMANDNAME;</command>

55

</cmdsynopsis>

56

</refsynopsisdiv>

57

58

59

<title>DESCRIPTION</title>

60

<para>

61

This program prompts for a password using <citerefentry>

62

<refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum>

63

</citerefentry> and outputs any given password to standard

64

output. If no <citerefentry><refentrytitle

65

>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>

66

process can be found, this program will immediately exit with an

67

exit code indicating failure.

68

</para>

69

<para>

70

This program is not very useful on its own. This program is

71

really meant to run as a plugin in the <application

72

>Mandos</application> client-side system, where it is used as a

73

fallback and alternative to retrieving passwords from a

74

<application >Mandos</application> server.

75

</para>

76

<para>

77

If this program is killed (presumably by

78

<citerefentry><refentrytitle>plugin-runner</refentrytitle>

79

<manvolnum>8mandos</manvolnum></citerefentry> because some other

80

plugin provided the password), it cannot tell <citerefentry>

81

<refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum>

82

</citerefentry> to abort requesting a password, because

83

<citerefentry><refentrytitle>plymouth</refentrytitle>

84

<manvolnum>8</manvolnum></citerefentry> does not support this.

85

Therefore, this program will then <emphasis>kill</emphasis> the

86

running <citerefentry><refentrytitle>plymouth</refentrytitle>

87

<manvolnum>8</manvolnum></citerefentry> process and start a

88

<emphasis>new</emphasis> one using the same command line

89

arguments as the old one was using.

90

</para>

91

</refsect1>

92

93

94

<title>OPTIONS</title>

95

<para>

96

This program takes no options.

97

</para>

98

</refsect1>

99

100

101

<title>EXIT STATUS</title>

102

<para>

103

If exit status is 0, the output from the program is the password

104

as it was read. Otherwise, if exit status is other than 0, the

105

program was interrupted or encountered an error, and any output

106

so far could be corrupt and/or truncated, and should therefore

107

be ignored.

108

</para>

109

</refsect1>

110

111

112

<title>ENVIRONMENT</title>

113

114

115

<term><envar>cryptsource</envar></term>

116

<term><envar>crypttarget</envar></term>

117

118

<para>

119

If set, these environment variables will be assumed to

120

contain the source device name and the target device

121

mapper name, respectively, and will be shown as part of

122

the prompt.

123

</para>

124

<para>

125

These variables will normally be inherited from

126

<citerefentry><refentrytitle>plugin-runner</refentrytitle>

127

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

128

normally have inherited them from

129

<filename>/scripts/local-top/cryptroot</filename> in the

130

initial <acronym>RAM</acronym> disk environment, which will

131

have set them from parsing kernel arguments and

132

<filename>/conf/conf.d/cryptroot</filename> (also in the

133

initial RAM disk environment), which in turn will have been

134

created when the initial RAM disk image was created by

135

<filename

136

>/usr/share/initramfs-tools/hooks/cryptroot</filename>, by

137

extracting the information of the root file system from

138

<filename >/etc/crypttab</filename>.

139

</para>

140

<para>

141

This behavior is meant to exactly mirror the behavior of

142

<command>askpass</command>, the default password prompter.

143

</para>

144

</listitem>

145

</varlistentry>

146

</variablelist>

147

</refsect1>

148

149

150

<title>FILES</title>

151

152

153

<term><filename>/bin/plymouth</filename></term>

154

155

<para>

156

This is the command run to retrieve a password from

157

<citerefentry><refentrytitle>plymouth</refentrytitle>

158

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

159

</para>

160

</listitem>

161

</varlistentry>

162

163

164

165

<para>

166

To find the running <citerefentry><refentrytitle

167

>plymouth</refentrytitle><manvolnum>8</manvolnum>

168

</citerefentry>, this directory will be searched for

169

numeric entries which will be assumed to be directories.

170

In all those directories, the <filename>exe</filename> and

171

<filename>cmdline</filename> entries will be used to

172

determine the name of the running binary, effective user

173

and group <abbrev>ID</abbrev>, and the command line

174

arguments. See <citerefentry><refentrytitle

175

>proc</refentrytitle><manvolnum>5</manvolnum>

176

</citerefentry>.

177

</para>

178

</listitem>

179

</varlistentry>

180

181

<term><filename>/sbin/plymouthd</filename></term>

182

183

<para>

184

This is the name of the binary which will be searched for

185

in the process list. See <citerefentry><refentrytitle

186

>plymouth</refentrytitle><manvolnum>8</manvolnum>

187

</citerefentry>.

188

</para>

189

</listitem>

190

</varlistentry>

191

</variablelist>

192

</refsect1>

193

194

195

196

<para>

197

Killing the <citerefentry><refentrytitle

198

>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>

199

daemon and starting a new one is ugly, but necessary as long as

200

it does not support aborting a password request.

201

</para>

202

</refsect1>

203

204

205

<title>EXAMPLE</title>

206

<para>

207

Note that normally, this program will not be invoked directly,

208

but instead started by the Mandos <citerefentry><refentrytitle

209

>plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>

210

</citerefentry>.

211

</para>

212

213

<para>

214

This program takes no options.

215

</para>

216

<para>

217

<userinput>&COMMANDNAME;</userinput>

218

</para>

219

</informalexample>

220

</refsect1>

221

222

223

<title>SECURITY</title>

224

<para>

225

If this program is killed by a signal, it will kill the process

226

<abbrev>ID</abbrev> which at the start of this program was

227

determined to run <citerefentry><refentrytitle

228

>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>

229

as root (see also <xref linkend="files"/>). There is a very

230

slight risk that, in the time between those events, that process

231

<abbrev>ID</abbrev> was freed and then taken up by another

232

process; the wrong process would then be killed. Now, this

233

program can only be killed by the user who started it; see

234

<citerefentry><refentrytitle>plugin-runner</refentrytitle>

235

<manvolnum>8mandos</manvolnum></citerefentry>. This program

236

should therefore be started by a completely separate

237

non-privileged user, and no other programs should be allowed to

238

run as that special user. This means that it is not recommended

239

to use the user "nobody" to start this program, as other

240

possibly less trusted programs could be running as "nobody", and

241

they would then be able to kill this program, triggering the

242

killing of the process <abbrev>ID</abbrev> which may or may not

243

be <citerefentry><refentrytitle>plymouth</refentrytitle>

244

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

245

</para>

246

<para>

247

The only other thing that could be considered worthy of note is

248

this: This program is meant to be run by <citerefentry>

249

<refentrytitle>plugin-runner</refentrytitle><manvolnum

250

>8mandos</manvolnum></citerefentry>, and will, when run

251

standalone, outside, in a normal environment, immediately output

252

on its standard output any presumably secret password it just

253

received. Therefore, when running this program standalone

254

(which should never normally be done), take care not to type in

255

any real secret password by force of habit, since it would then

256

immediately be shown as output.

257

</para>

258

</refsect1>

259

260

261

262

<para>

263

<citerefentry><refentrytitle>crypttab</refentrytitle>

264

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

265

<citerefentry><refentrytitle>plugin-runner</refentrytitle>

266

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

267

268

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

269

<citerefentry><refentrytitle>plymouth</refentrytitle>

270

271

</para>

272

</refsect1>

273

</refentry>

274

275

276

277

278