diff options
author | ArthurHoaro <arthur@hoa.ro> | 2017-05-07 19:17:33 +0200 |
---|---|---|
committer | ArthurHoaro <arthur@hoa.ro> | 2017-05-07 19:17:33 +0200 |
commit | 01e942d44c7194607649817216aeb5d65c6acad6 (patch) | |
tree | 15777aa1005251f119e6dd680291147117766b5b /doc/Shaarli-configuration.md | |
parent | bc22c9a0acb095970e9494cbe8954f0612e05dc0 (diff) | |
parent | 8868f3ca461011a8fb6dd9f90b60ed697ab52fc5 (diff) | |
download | Shaarli-01e942d44c7194607649817216aeb5d65c6acad6.tar.gz Shaarli-01e942d44c7194607649817216aeb5d65c6acad6.tar.zst Shaarli-01e942d44c7194607649817216aeb5d65c6acad6.zip |
Merge tag 'v0.8.4' into stable
Release v0.8.4
Diffstat (limited to 'doc/Shaarli-configuration.md')
-rw-r--r-- | doc/Shaarli-configuration.md | 298 |
1 files changed, 179 insertions, 119 deletions
diff --git a/doc/Shaarli-configuration.md b/doc/Shaarli-configuration.md index d0560d79..4a783c0e 100644 --- a/doc/Shaarli-configuration.md +++ b/doc/Shaarli-configuration.md | |||
@@ -1,14 +1,18 @@ | |||
1 | #Shaarli configuration | 1 | #Shaarli configuration |
2 | # Shaarli configuration | ||
3 | |||
2 | ## Foreword | 4 | ## Foreword |
3 | 5 | ||
4 | **Do not edit configuration options in index.php! Your changes would be lost.** | 6 | **Do not edit configuration options in index.php! Your changes would be lost.** |
5 | 7 | ||
6 | Once your Shaarli instance is installed, the file `data/config.php` is generated: | 8 | Once your Shaarli instance is installed, the file `data/config.json.php` is generated: |
7 | * it contains all settings, and can be edited to customize values | 9 | * it contains all settings in JSON format, and can be edited to customize values |
8 | * it defines which [plugins](Plugin-System) are enabled[](.html) | 10 | * it defines which [plugins](Plugin-System) are enabled[(.html)]((.html).html) |
9 | * its values override those defined in `index.php` | 11 | * its values override those defined in `index.php` |
12 | * it is wrap in a PHP comment to prevent anyone accessing it, regardless of server configuration | ||
10 | 13 | ||
11 | ## File and directory permissions | 14 | ## File and directory permissions |
15 | |||
12 | The server process running Shaarli must have: | 16 | The server process running Shaarli must have: |
13 | - `read` access to the following resources: | 17 | - `read` access to the following resources: |
14 | - PHP scripts: `index.php`, `application/*.php`, `plugins/*.php` | 18 | - PHP scripts: `index.php`, `application/*.php`, `plugins/*.php` |
@@ -29,123 +33,179 @@ On a Linux distribution: | |||
29 | - to give it access to Shaarli, either: | 33 | - to give it access to Shaarli, either: |
30 | - unzip Shaarli in the default web server location (usually `/var/www/`) and set the web server user as the owner | 34 | - unzip Shaarli in the default web server location (usually `/var/www/`) and set the web server user as the owner |
31 | - put users in the same group as the web server, and set the appropriate access rights | 35 | - put users in the same group as the web server, and set the appropriate access rights |
32 | - if you have a domain / subdomain to serve Shaarli, [configure the server](Server-configuration) accordingly[](.html) | 36 | - if you have a domain / subdomain to serve Shaarli, [configure the server](Server-configuration) accordingly[(.html)]((.html).html) |
33 | 37 | ||
34 | ## Example `data/config.php` | 38 | ## Configuration |
35 | See also [Plugin System](Plugin-System.html). | 39 | |
36 | 40 | In `data/config.json.php`. | |
37 | ```php | 41 | |
38 | <?php | 42 | See also [Plugin System](Plugin-System.html).[](.html) |
39 | // User login | 43 | |
40 | $GLOBALS['login'] = '<login>';[](.html) | 44 | ### Credentials |
41 | 45 | ||
42 | // User password hash | 46 | > You shouldn't edit those. |
43 | $GLOBALS['hash'] = '200c452da46c2f889e5e48c49ef044bcacdcb095';[](.html) | 47 | |
44 | 48 | **login**: Login username. | |
45 | // Password salt | 49 | **hash**: Generated password hash. |
46 | $GLOBALS['salt'] = '13b654102321576033d8473b63a275a1bf94c0f0'; [](.html) | 50 | **salt**: Password salt. |
47 | 51 | ||
48 | // Local timezone | 52 | ### General |
49 | $GLOBALS['timezone'] = 'Africa/Abidjan';[](.html) | 53 | |
50 | date_default_timezone_set('Africa/Abidjan'); | 54 | **title**: Shaarli's instance title. |
51 | 55 | **header_link**: Link to the homepage. | |
52 | // Shaarli title | 56 | **links_per_page**: Number of shaares displayed per page. |
53 | $GLOBALS['title'] = 'My Little Shaarly';[](.html) | 57 | **timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php). [](.html) |
54 | 58 | **enabled_plugins**: List of enabled plugins. | |
55 | // Link the Shaarli title points to | 59 | |
56 | $GLOBALS['titleLink'] = '?';[](.html) | 60 | ### Security |
57 | 61 | ||
58 | // HTTP referer redirector | 62 | **session_protection_disabled**: Disable session cookie hijacking protection (not recommended). |
59 | $GLOBALS['redirector'] = '';[](.html) | 63 | It might be useful if your IP adress often changes. |
60 | 64 | **ban_after**: Failed login attempts before being IP banned. | |
61 | // Disable session hijacking | 65 | **ban_duration**: IP ban duration in seconds. |
62 | $GLOBALS['disablesessionprotection'] = false; [](.html) | 66 | **open_shaarli**: Anyone can add a new link while logged out if enabled. |
63 | 67 | **trusted_proxies**: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy. | |
64 | // Whether new links are private by default | 68 | |
65 | $GLOBALS['privateLinkByDefault'] = false;[](.html) | 69 | ### Resources |
66 | 70 | ||
67 | // Enabled plugins | 71 | **data_dir**: Data directory. |
68 | // Note: each plugin may provide further settings through its own "config.php" | 72 | **datastore**: Shaarli's links database file path. |
69 | $GLOBALS['config'['ENABLED_PLUGINS'] = array('addlink_toolbar', 'qrcode');]('ENABLED_PLUGINS']-=-array('addlink_toolbar',-'qrcode');.html) | 73 | **updates**: File path for the ran updates file. |
70 | 74 | **log**: Log file path. | |
71 | // Subdirectory where Shaarli stores its data files. | 75 | **update_check**: Last update check file path. |
72 | // You can change it for better security. | 76 | **raintpl_tpl**: Templates directory. |
73 | $GLOBALS['config'['DATADIR'] = 'data';]('DATADIR']-=-'data';.html) | 77 | **raintpl_tmp**: Template engine cache directory. |
74 | 78 | **thumbnails_cache**: Thumbnails cache directory. | |
75 | // File used to store settings | 79 | **page_cache**: Shaarli's internal cache directory. |
76 | $GLOBALS['config'['CONFIG_FILE'] = 'data/config.php';]('CONFIG_FILE']-=-'data/config.php';.html) | 80 | **ban_file**: Banned IP file path. |
77 | 81 | ||
78 | // File containing the link database | 82 | ### Updates |
79 | $GLOBALS['config'['DATASTORE'] = 'data/datastore.php';]('DATASTORE']-=-'data/datastore.php';.html) | 83 | |
80 | 84 | **check_updates**: Enable or disable update check to the git repository. | |
81 | // Number of links displayed per page | 85 | **check_updates_branch**: Git branch used to check updates (e.g. `stable` or `master`). |
82 | $GLOBALS['config'['LINKS_PER_PAGE'] = 20;]('LINKS_PER_PAGE']-=-20;.html) | 86 | **check_updates_interval**: Look for new version every N seconds (default: every day). |
83 | 87 | ||
84 | // File recording failed login attempts and IP bans | 88 | ### Privacy |
85 | $GLOBALS['config'['IPBANS_FILENAME'] = 'data/ipbans.php';]('IPBANS_FILENAME']-=-'data/ipbans.php';.html) | 89 | |
86 | 90 | **default_private_links**: Check the private checkbox by default for every new link. | |
87 | // Failed login attempts before being banned | 91 | **hide_public_links**: All links are hidden while logged out. |
88 | $GLOBALS['config'['BAN_AFTER'] = 4;]('BAN_AFTER']-=-4;.html) | 92 | **hide_timestamps**: Timestamps are hidden. |
89 | 93 | ||
90 | // Duration of an IP ban, in seconds (30 minutes) | 94 | ### Feed |
91 | $GLOBALS['config'['BAN_DURATION'] = 1800;]('BAN_DURATION']-=-1800;.html) | 95 | |
92 | 96 | **rss_permalinks**: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL. | |
93 | // If set to true, everyone will be able to add, edit and remove links, | 97 | **show_atom**: Display ATOM feed button. |
94 | // as well as change configuration | 98 | |
95 | $GLOBALS['config'['OPEN_SHAARLI'] = false;]('OPEN_SHAARLI']-=-false;.html) | 99 | ### Thumbnail |
96 | 100 | ||
97 | // Do not show link timestamps | 101 | **enable_thumbnails**: Enable or disable thumbnail display. |
98 | $GLOBALS['config'['HIDE_TIMESTAMPS'] = false;]('HIDE_TIMESTAMPS']-=-false;.html) | 102 | **enable_localcache**: Enable or disable local cache. |
99 | 103 | ||
100 | // Set to false to disable local thumbnail cache, e.g. due to limited disk quotas | 104 | ### Redirector |
101 | $GLOBALS['config'['ENABLE_THUMBNAILS'] = true;]('ENABLE_THUMBNAILS']-=-true;.html) | 105 | |
102 | 106 | **url**: Redirector URL, such as `anonym.to`. | |
103 | // Thumbnail cache directory | 107 | **encode_url**: Enable this if the redirector needs encoded URL to work properly. |
104 | $GLOBALS['config'['CACHEDIR'] = 'cache';]('CACHEDIR']-=-'cache';.html) | 108 | |
105 | 109 | ## Configuration file example | |
106 | // Enable feed (rss, atom, dailyrss) cache | 110 | |
107 | $GLOBALS['config'['ENABLE_LOCALCACHE'] = true;]('ENABLE_LOCALCACHE']-=-true;.html) | 111 | ```json |
108 | 112 | <?php /* | |
109 | // Feed cache directory | 113 | { |
110 | $GLOBALS['config'['PAGECACHE'] = 'pagecache';]('PAGECACHE']-=-'pagecache';.html) | 114 | "credentials": { |
111 | 115 | "login": "<login>", | |
112 | // RainTPL cache directory (keep the trailing slash!) | 116 | "hash": "<password hash>", |
113 | $GLOBALS['config'['RAINTPL_TMP'] = 'tmp/';]('RAINTPL_TMP']-=-'tmp/';.html) | 117 | "salt": "<password salt>" |
114 | 118 | }, | |
115 | // RainTPL template directory (keep the trailing slash!) | 119 | "security": { |
116 | $GLOBALS['config'['RAINTPL_TPL'] = 'tpl/';]('RAINTPL_TPL']-=-'tpl/';.html) | 120 | "ban_after": 4, |
117 | 121 | "session_protection_disabled": false, | |
118 | // Whether Shaarli checks for new releases at https://github.com/shaarli/Shaarli | 122 | "ban_duration": 1800, |
119 | $GLOBALS['config'['ENABLE_UPDATECHECK'] = true;]('ENABLE_UPDATECHECK']-=-true;.html) | 123 | "trusted_proxies": [[](.html) |
120 | 124 | "1.2.3.4", | |
121 | // File to store the latest Shaarli version | 125 | "5.6.7.8" |
122 | $GLOBALS['config'['UPDATECHECK_FILENAME'] = 'data/lastupdatecheck.txt';]('UPDATECHECK_FILENAME']-=-'data/lastupdatecheck.txt';.html) | 126 | ] |
123 | 127 | }, | |
124 | // Delay between version checks (requires to be logged in) (24 hours) | 128 | "resources": { |
125 | $GLOBALS['config'['UPDATECHECK_INTERVAL'] = 86400;]('UPDATECHECK_INTERVAL']-=-86400;.html) | 129 | "data_dir": "data", |
126 | 130 | "config": "data\/config.php", | |
127 | // For each link, display a link to an archived version on archive.org | 131 | "datastore": "data\/datastore.php", |
128 | $GLOBALS['config'['ARCHIVE_ORG'] = false;]('ARCHIVE_ORG']-=-false;.html) | 132 | "ban_file": "data\/ipbans.php", |
129 | 133 | "updates": "data\/updates.txt", | |
130 | // The RSS item links point: | 134 | "log": "data\/log.txt", |
131 | // true => directly to the link | 135 | "update_check": "data\/lastupdatecheck.txt", |
132 | // false => to the entry on Shaarli (permalink) | 136 | "raintpl_tmp": "tmp\/", |
133 | $GLOBALS['config'['ENABLE_RSS_PERMALINKS'] = true;]('ENABLE_RSS_PERMALINKS']-=-true;.html) | 137 | "raintpl_tpl": "tpl\/", |
134 | 138 | "thumbnails_cache": "cache", | |
135 | // Hide all links to non-logged users | 139 | "page_cache": "pagecache" |
136 | $GLOBALS['config'['HIDE_PUBLIC_LINKS'] = false;]('HIDE_PUBLIC_LINKS']-=-false;.html) | 140 | }, |
137 | 141 | "general": { | |
138 | $GLOBALS['config'['PUBSUBHUB_URL'] = '';]('PUBSUBHUB_URL']-=-'';.html) | 142 | "check_updates": true, |
139 | 143 | "rss_permalinks": true, | |
140 | // Show an ATOM Feed button next to the Subscribe (RSS) button. | 144 | "links_per_page": 20, |
141 | // ATOM feeds are available at the address ?do=atom regardless of this option. | 145 | "default_private_links": true, |
142 | $GLOBALS['config'['SHOW_ATOM'] = false;]('SHOW_ATOM']-=-false;.html) | 146 | "enable_thumbnails": true, |
143 | 147 | "enable_localcache": true, | |
144 | // Set this to true if the redirector requires encoded URL, false otherwise. | 148 | "check_updates_branch": "stable", |
145 | $GLOBALS['config'['REDIRECTOR_URLENCODE'] = true;]('REDIRECTOR_URLENCODE']-=-true;.html) | 149 | "check_updates_interval": 86400, |
146 | ?> | 150 | "enabled_plugins": [[](.html) |
151 | "markdown", | ||
152 | "wallabag", | ||
153 | "archiveorg" | ||
154 | ], | ||
155 | "timezone": "Europe\/Paris", | ||
156 | "title": "My Shaarli", | ||
157 | "header_link": "?" | ||
158 | }, | ||
159 | "extras": { | ||
160 | "show_atom": false, | ||
161 | "hide_public_links": false, | ||
162 | "hide_timestamps": false, | ||
163 | "open_shaarli": false, | ||
164 | "redirector": "http://anonym.to/?", | ||
165 | "redirector_encode_url": false | ||
166 | }, | ||
167 | "general": { | ||
168 | "header_link": "?", | ||
169 | "links_per_page": 20, | ||
170 | "enabled_plugins": [[](.html) | ||
171 | "markdown", | ||
172 | "wallabag" | ||
173 | ], | ||
174 | "timezone": "Europe\/Paris", | ||
175 | "title": "My Shaarli" | ||
176 | }, | ||
177 | "updates": { | ||
178 | "check_updates": true, | ||
179 | "check_updates_branch": "stable", | ||
180 | "check_updates_interval": 86400 | ||
181 | }, | ||
182 | "feed": { | ||
183 | "rss_permalinks": true, | ||
184 | "show_atom": false | ||
185 | }, | ||
186 | "privacy": { | ||
187 | "default_private_links": true, | ||
188 | "hide_public_links": false, | ||
189 | "hide_timestamps": false | ||
190 | }, | ||
191 | "thumbnail": { | ||
192 | "enable_thumbnails": true, | ||
193 | "enable_localcache": true | ||
194 | }, | ||
195 | "redirector": { | ||
196 | "url": "http://anonym.to/?", | ||
197 | "encode_url": false | ||
198 | }, | ||
199 | "plugins": { | ||
200 | "WALLABAG_URL": "http://demo.wallabag.org", | ||
201 | "WALLABAG_VERSION": "1" | ||
202 | } | ||
203 | } ?> | ||
147 | ``` | 204 | ``` |
148 | 205 | ||
149 | ## Additional configuration | 206 | ## Additional configuration |
150 | 207 | ||
151 | The playvideos plugin may require that you adapt your server's [Content Security Policy](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md#troubleshooting) configuration to work properly.[](.html) | 208 | The playvideos plugin may require that you adapt your server's |
209 | [Content Security Policy](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md#troubleshooting) [](.html) | ||
210 | configuration to work properly.[(.html)]((.html).html) | ||
211 | |||