document other files in .ikiwiki
[ikiwiki.git] / 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.