doc/kdb.1

   1 .\"     Title: kdb
   2 .\"    Author: Avi Alkalay <avi at unix.sh>
   3 .\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
   4 .\"      Date: March 2004
   5 .\"    Manual:
   6 .\"    Source: Elektra Initiative
   7 .\"
   8 .TH "KDB" "1" "March 2004" "Elektra Initiative" ""
   9 .\" disable hyphenation
  10 .nh
  11 .\" disable justification (adjust text to left margin only)
  12 .ad l
  13 .SH "NAME"
  14 kdb \- Elektra key database command line administration tool
  15 .SH "SYNOPSIS"
  16 .HP 8
  17 \fBkdb get\fR [\fB\-dlr\fR] key/name
  18 .HP 8
  19 \fBkdb set\fR [\fB\-t\fR\ \fBtype\fR] [\fB\-d\fR] [\fB\-c\fR\ \fB"A\ comment\ about\ this\ key"\fR] [\fB\-m\fR\ \fBmode\fR] [\fB\-u\fR\ \fBuid\fR] [\fB\-g\fR\ \fBgid\fR] key/name "the\ value"
  20 .HP 8
  21 \fBkdb set\fR [\fB\-t\fR\ \fBtype\fR] [\fB\-m\fR\ \fBmode\fR] [\fB\-c\fR\ \fB"A\ comment"\fR] key/name \-\- "the\ value"
  22 .HP 8
  23 \fBkdb set\fR [\fB\-t\fR\ \fBtype\fR] [\fB\-b\fR\ \fBfile\fR] key/name
  24 .HP 7
  25 \fBkdb ls\fR [\fB\-lRfvs\fR] [key/dir\ |\ key/name]
  26 .HP 7
  27 \fBkdb ls\fR [\fB\-lRfvx\fR] [key/dir\ |\ key/name] > keys\&.xml
  28 .HP 9
  29 \fBkdb edit\fR [\fB\-R\fR] [key/dir\ |\ key/name]
  30 .HP 7
  31 \fBkdb rm\fR key/name
  32 .HP 7
  33 \fBkdb mv\fR key/src key/dest
  34 .HP 7
  35 \fBkdb ln\fR key/src key/dest
  36 .HP 11
  37 \fBkdb export\fR [\fB\-f\fR] system/some/tree\&.root > [file\&.xml]
  38 .HP 11
  39 \fBkdb import\fR < file\&.xml
  40 .HP 11
  41 \fBkdb import\fR file\&.xml
  42 .HP 12
  43 \fBkdb monitor\fR some/key/name
  44 Description.PP
  45 The
  46 \fBkdb\fR
  47 command provide ways to manipulate the Elektra keys database\&.
  48 .PP
  49 The subcommands implemented are very similar to regular UNIX commands like
  50 \fBls\fR, and
  51 \fBrm\fR, specially in their output and options\&.
  52 Subcommands.PP
  53 \fBget\fR
  54 .RS 4
  55 Get the value from the specified key\&. Accepts options:
  56 \fB\-d\fR,
  57 \fB\-l\fR,
  58 \fB\-f\fR,
  59 \fB\-s\fR
  60 .RE
  61 .PP
  62 \fBset\fR
  63 .RS 4
  64 Set the value to the specified key\&. Accepts options:
  65 \fB\-c\fR,
  66 \fB\-t\fR,
  67 \fB\-d\fR,
  68 \fB\-m\fR,
  69 \fB\-b\fR
  70 .RE
  71 .PP
  72 \fBls\fR
  73 .RS 4
  74 As the
  75 \fBls\fR(1)
  76 command, list key names for the specified key, or children keys, if specified a folder key\&. The
  77 \fB\-v\fR
  78 argument will make it show also the values of each key\&. The
  79 \fB\-d\fR
  80 (descriptive) will make it show the comment, key name and its value, as you are watching a plain text file\&. Accepts options:
  81 \fB\-x\fR,
  82 \fB\-d\fR,
  83 \fB\-l\fR,
  84 \fB\-f\fR,
  85 \fB\-v\fR,
  86 \fB\-R\fR,
  87 \fB\-s\fR
  88 .RE
  89 .PP
  90 \fBln\fR
  91 .RS 4
  92 Creates a key that is a symbolic links to another key\&.
  93 .RE
  94 .PP
  95 \fBmv\fR
  96 .RS 4
  97 Move, or renames a key\&. Currently it can\'t move keys across different filesystems\&.
  98 .RE
  99 .PP
 100 \fBrm\fR
 101 .RS 4
 102 As the
 103 \fBrm\fR(1)
 104 command, removes the key specified\&.
 105 .RE
 106 .PP
 107 \fBedit\fR
 108 .RS 4
 109 A very powerfull subcommand that lets you edit an XML representation of the keys\&. The parameters it accepts is usually a parent key, so its child keys will be gathered\&. Can be used with the
 110 \fB\-R\fR
 111 flag to work recursively\&. The editor used is the one set in the
 112 \fB$EDITOR\fR
 113 environment variable, or
 114 \fBvi\fR\&. After editing the keys,
 115 \fBkdb edit\fR
 116 will analyze them and commit only the changed keys, remove the keys removed, and add the keys added\&. This command is only available when
 117 \fI/usr/lib/libelektratools\&.so\fR
 118 is available\&.
 119 .RE
 120 .PP
 121 \fBexport\fR, \fBsave\fR
 122 .RS 4
 123 Export a subtree of keys to XML\&. If no subtree is defined right after the
 124 \fBexport\fR
 125 command,
 126 \fIsystem\fR
 127 and current
 128 \fIuser\fR
 129 trees will be exported\&. Output is written to standard output\&. The output encoding will allways be UTF\-8, regardeless of your system encoding\&. UTF\-8 is the most universal charset you can get when exchanging data between multiple systems\&. Accepts
 130 \fB\-f\fR\&.
 131 .RE
 132 .PP
 133 \fBimport\fR, \fBload\fR
 134 .RS 4
 135 Import an XML representation of keys and save it to the keys database\&. If no filename is passed right after the
 136 \fBimport\fR
 137 command, standard input is used\&. This command is only available when
 138 \fI/usr/lib/libelektratools\&.so\fR
 139 is available\&.
 140 .RE
 141 .PP
 142 \fBmonitor\fR, \fBmon\fR
 143 .RS 4
 144 Monitor a key for some value change\&. It will block your command line until a change in the key value is detected, then return its new value\&.
 145 .RE
 146 Options.PP
 147 \fB\-R\fR
 148 .RS 4
 149 Causes to work recursively\&. In
 150 \fBls\fR, will list recursively\&.
 151 .RE
 152 .PP
 153 \fB\-x\fR
 154 .RS 4
 155 Makes
 156 \fBls\fR
 157 output an XML representation of the keys, instead of an
 158 \fBls\fR\-compatible output\&.
 159 .RE
 160 .PP
 161 \fB\-l\fR
 162 .RS 4
 163 Causes to display long results\&. With
 164 \fBls\fR, will generate lists similar to
 165 \fBls \-l\fR\&. With
 166 \fBget\fR, will show also the key name\&.
 167 .RE
 168 .PP
 169 \fB\-a\fR
 170 .RS 4
 171 Causes
 172 \fBls\fR
 173 to display also inactive keys\&. Generate lists similar to
 174 \fBls \-a\fR\&. Inactive keys are keys which basename begins with a \'\&.\' (dot)\&. An example of inactive key:
 175 \fIsystem/sw/XFree/current/Monitor/\&.Monitor1\fR
 176 .RE
 177 .PP
 178 \fB\-f\fR
 179 .RS 4
 180 Causes to work with full key names\&. A full key name makes sense only on
 181 \fIuser/*\fR
 182 keys, and differentiate from the regular key names in specifying the owner user\&. If the current user is
 183 \fIsomeuser\fR, the
 184 \fIuser/some/key\fR
 185 full name is
 186 \fIuser:someuser/some/key\fR\&. Makes effect in
 187 \fBls\fR,
 188 \fBexport\fR
 189 and
 190 \fBget\fR
 191 subcommands\&.
 192 .RE
 193 .PP
 194 \fB\-d\fR
 195 .RS 4
 196 Causes
 197 \fBget\fR
 198 to work descriptivelly\&. When requesting a key it will show the comment, key name and its value in a fancy format\&.
 199 Causes
 200 \fBset\fR
 201 to mark the key as a directory key\&.
 202 .RE
 203 .PP
 204 \fB\-s\fR
 205 .RS 4
 206 Causes
 207 \fBget\fR
 208 and
 209 \fBls\fR
 210 to be more friendly to Shell scripts\&. For example, when requesting
 211 \fIuser/env/env2/PATH\fR, the output will be PATH="the value", that is, only the basename of the key will be showed and the value will be surrounded by \' " \'\&.
 212 .RE
 213 .PP
 214 \fB\-t type\fR
 215 .RS 4
 216 When
 217 \fBset\fRting a key\'s value, you can specify the type with this switch\&. Currently accepted types are
 218 \fBstring\fR
 219 for plain text,
 220 \fBbin\fR
 221 for binary as\-is values,
 222 \fBdir\fR
 223 to create folder keys and
 224 \fBlink\fR
 225 to create symbolic links between keys\&. Plain text are always stored as
 226 \fBUTF-8\fR(7)
 227 in Elektra, regardeless of your current encoding (\fB$LANG\fR)\&. If you want to force a value to be stored without the
 228 \fBUTF-8\fR(7)
 229 encoding (a bad idea), you can set it as binary\&. Binary values should be avoided, because they are black boxes for system administrators\&.
 230 .RE
 231 .PP
 232 \fB\-b filename\fR
 233 .RS 4
 234 Set the key value as the content of file
 235 \fIfilename\fR\&. This option is more usefull when setting binary keys\&.
 236 .RE
 237 .PP
 238 \fB\-m mode\fR
 239 .RS 4
 240 For the
 241 \fBset\fR
 242 command\&. Will set the key access permission to
 243 \fBmode\fR, which must be an octal number as for
 244 \fBchmod\fR(1)\&.
 245 .RE
 246 .PP
 247 \fB\-u uid\fR
 248 .RS 4
 249 Create the key with
 250 \fBuid\fR
 251 user ID\&. It can be a user name or a uid number\&.
 252 .RE
 253 .PP
 254 \fB\-g gid\fR
 255 .RS 4
 256 Create the key with
 257 \fBgid\fR
 258 group ID\&. It can be a group name or a gid number
 259 .RE
 260 .PP
 261 \fB\-c comment\fR
 262 .RS 4
 263 When
 264 \fBset\fRting keys, you can use this argument to set a descriptive comment for it\&. This comment is exactly as a comment in a plain text configuration file\&. The comment is stored as
 265 \fBUTF-8\fR(7)
 266 regardeless of your current encoding (\fB$LANG\fR)\&.
 267 .RE
 268 .PP
 269 \fB\-v\fR
 270 .RS 4
 271 With the
 272 \fBls\fR
 273 subcommand, will make it show also the value stored in the key\&.
 274 .RE
 275 .PP
 276 \fB\-\-\fR
 277 .RS 4
 278 With the
 279 \fBset\fR
 280 subcommand, everything after it will be considered the value, even text with dashes (\-)\&.
 281 .RE
 282 Best Practices When Creating Keys.PP
 283 When using Elektra to store your application\'s configuration and state, please keep in mind the following rules:
 284 .sp
 285 .RS 4
 286 \h'-04'\(bu\h'+03'You are not allowed to create keys right under
 287 \fIsystem\fR
 288 or
 289 \fIuser\fR\&.
 290 .RE
 291 .sp
 292 .RS 4
 293 \h'-04'\(bu\h'+03'You are not allowed to create folder keys right under
 294 \fIsystem\fR
 295 or
 296 \fIuser\fR\&. They are reserved for very essential OS subsystems\&.
 297 .RE
 298 .sp
 299 .RS 4
 300 \h'-04'\(bu\h'+03'The keys for your application, called say
 301 \fIMyApp\fR, should be created under
 302 \fIsystem/sw/MyApp\fR
 303 and/or
 304 \fIuser/sw/MyApp\fR\&.
 305 .RE
 306 .SH "ENVIRONMENT"
 307 .PP
 308 \fBKDB_ROOT\fR
 309 if defined, prepends it to key names\&.
 310 .PP
 311 \fBKDB_BACKEND\fR
 312 defines the name of another backend plugin library to use
 313 ExamplesSetting Keys.PP
 314 bash$\fBkdb set \-c "My first key" user/example/key "Some nice value"\fR
 315 .PP
 316 bash$\fBkdb set user:luciana/example/key \-\- "Some \- nice \- value with dashes"\fR
 317 .PP
 318 bash#\fBKDB_ROOT=user:http/sw/httpd kdb set \-u nobody \-g http key "Some value"\fR
 319 .PP
 320 bash$\fBkdb set \-b image\&.png \-t bin user/example/binaryKey\fR
 321 .PP
 322 bash$\fBkdb set \-b file\&.txt user/example/regularKey\fR
 323 .PP
 324 bash#\fBkdb set \-t link system/sw/XFree/current system/sw/XFree/handmade\fR
 325 Getting Keys.PP
 326 bash$\fBKDB_ROOT=user/example kdb get some/key/name\fR
 327 .PP
 328 bash$\fBeval `kdb get \-s user/env/env1/PS1`\fR
 329 .PP
 330 bash$\fBKDB_BACKEND=gconf kdb get user/sw/gnome\-terminal/global/active_encodings\fR
 331 Listing.PP
 332 bash$\fBkdb ls \-laR user:valeria\fR
 333 .PP
 334 bash$\fBkdb ls \-lR system/sw/xorg/current\fR
 335 .PP
 336 bash$\fBKDB_ROOT=system/sw kdb ls \-lR xorg\fR
 337 .PP
 338 bash$\fBKDB_BACKEND=fstab kdb ls \-Rv system/filesystems\fR
 339 .PP
 340 bash$\fBeval `kdb ls \-Rvs user/env/env2`\fR
 341 Miscelaneous.PP
 342 bash#\fBkdb ln system/sw/xorg/handmade system/sw/xorg/current\fR
 343 .PP
 344 bash#\fBkdb mv system/sw/xorg/current system/sw/xorg/old\fR
 345 .PP
 346 bash#\fBkdb rm system/inittab/rc4\fR
 347 .PP
 348 bash$\fBKDB_BACKEND=gconf kdb rm user/gconfKey\fR
 349 XML Import and Export.PP
 350 bash#\fBkdb export user/sw/app | sed \-e \'s|/app/|/app2/|g\' | kdb import\fR
 351 .PP
 352 bash#\fBKDB_ROOT=system/sw kdb export myapp > myappconf\&.xml\fR
 353 .PP
 354 bash#\fBkdb import myappconf\&.xml\fR
 355 .PP
 356 bash$\fBKDB_BACKEND=gconf kdb export user/sw\fR
 357 .SH "SEE ALSO"
 358 .PP
 359
 360 \fBelektra\fR(7),
 361 \fBelektra\fR(5)
 362 .SH "AUTHOR"
 363 .PP
 364 \fBAvi Alkalay\fR <\&avi at unix\&.sh\&>
 365 .br
 366 Linux Market Developer, Senior IT and Software Architect, IBM Linux Impact Team :: \fIibm\&.com/linux\fR
 367 .sp -1n
 368 .IP "" 4
 369 Author.
 370 .SH "COPYRIGHT"
 371 Copyright \(co 2004 Avi Alkalay
 372 .br