doc/tips/inside_dot_ikiwiki.mdwn

   1 [[!meta title="inside .ikiwiki"]]
   2
   3 The `.ikiwiki` directory contains ikiwiki's internal state. Normally,
   4 you don't need to look in it, but here's some tips for how to do so if
   5 you need/want to.
   6
   7 ## the index
   8
   9 `.ikiwiki/indexdb` contains a cache of information about pages, as well
  10 as all persisitant state about pages. It used to be a (semi) human-readable
  11 text file, but is not anymore.
  12
  13 To dump the contents of the file, enter a perl command like this.
  14
  15         joey@kodama:~/src/joeywiki/.ikiwiki> perl -le 'use Storable; my $index=Storable::retrieve("indexdb"); use Data::Dumper; print Dumper $index' | head
  16         $VAR1 = {
  17           'index' => {
  18                      'ctime' => 1199739528,
  19                      'dest' => [
  20                                  'index.html'
  21                                ],
  22                      'mtime' => 1199739528,
  23                      'src' => 'index.mdwn',
  24                      'links' => [
  25                                   'index/discussion',
  26
  27 ## the user database
  28
  29 `.ikiwiki/userdb` is the user database, which records preferences of all
  30 web users.
  31
  32 To list all users in the database, enter a perl command like this.
  33 Note that the output can include both registered users, and known
  34 openids.
  35
  36         joey@kodama:~/src/joeywiki/.ikiwiki> perl -le 'use Storable; my $userinfo=Storable::retrieve("userdb"); print $_ foreach keys %$userinfo'
  37         http://joey.kitenet.net/
  38         foo
  39
  40 To list each user's email address:
  41
  42         joey@kodama:~/src/joeywiki/.ikiwiki> perl -le 'use Storable; my $userinfo=Storable::retrieve("userdb"); print $userinfo->{$_}->{email} foreach keys %$userinfo'
  43
  44         joey@kitenet.net
  45
  46 To dump the entire database contents:
  47
  48         joey@kodama:~/src/joeywiki/.ikiwiki> perl -le 'use Storable; my $userinfo=Storable::retrieve("userdb"); use Data::Dumper; print Dumper $userinfo'
  49         $VAR1 = {
  50                   'http://joey.kitenet.net/' => {
  51                                                   'email' => 'joey@kitenet.net',
  52         [...]
  53
  54 Editing values is simply a matter of changing values and calling `Storable::nstore()`.
  55 So to change a user's email address:
  56
  57         joey@kodama:~/src/joeywiki/.ikiwiki> perl -le 'use Storable; my $userinfo=Storable::retrieve("userdb"); $userinfo->{"foo"}->{email}=q{foo@bar}; Storable::lock_nstore($userinfo, "userdb")'
  58
  59 To remove that user:
  60
  61         joey@kodama:~/src/joeywiki/.ikiwiki> perl -le 'use Storable; my $userinfo=Storable::retrieve("userdb"); delete $userinfo->{"foo"}; Storable::lock_nstore($userinfo, "userdb")'
  62
  63 I've not written actual utilities to do this yet because I've only needed
  64 to do it rarely, and the data I've wanted has been different each time.
  65 --[[Joey]]
  66
  67 ## the session database
  68
  69 `.ikiwiki/sessions.db` is the session database. See the [[!cpan CGI::Session]]
  70 documentation for more details.
  71
  72 ## lockfiles
  73
  74 In case you're curious, here's what the various lock files do.
  75
  76 * `.ikiwiki/lockfile` is the master ikiwiki lock file. Ikiwiki takes this
  77   lock before reading/writing state.
  78 * `.ikiwiki/commitlock` is locked as a semophore, to disable the commit hook
  79   from doing anything.
  80 * `.ikiwiki/cgilock` is locked by the cgi wrapper, to ensure that only
  81   one ikiwiki process is run at a time to handle cgi requests.
  82
  83 ## plugin state files
  84
  85 Some plugins create other files to store their state.
  86
  87 * `.ikiwiki/aggregate` is a plain text database used by the aggregate plugin
  88   to record feeds and known posts.
  89 * `.ikiwiki/xapian/` is created by the search plugin, and contains xapian-omega
  90   configuration and the xapian database.