BookStack Code Mirror - website/blob - content/docs/admin/filesystem-permissions.md

   1 +++
   2 title = "Filesystem Permissions"
   3 description = "The file and folder permissions required by BookStack"
   4 date = "2023-02-27"
   5 type = "admin-doc"
   6 +++
   7
   8 BookStack requires the ability to write and read files for various uses such as writing
   9 logs, handling file uploads and running application code.
  10 Ideally, files permissions should be limited to just what's required to reduce the chance
  11 of potential vulnerability exploit.
  12
  13 By default, BookStack requires the following permissions:
  14
  15 - Read access to the BookStack install folder and everything within.
  16 - Write permission to the following folders, relative to the BookStack installation directory, and everything within:
  17   - `storage/`
  18   - `bootstrap/cache`
  19   - `public/uploads`
  20
  21 **Note:** This access is likely controlled by the user/group of the PHP and/or web-server processes.
  22
  23 Additionally, you may want to ensure read access the `.env` file is limited as much as possible, to just PHP/web-server process and any trusted users that may need to update it, since this file can often contain credentials and keys.
  24
  25 ### Example Permissions Approach
  26
  27 This section provides an approach for setting permissions for your BookStack instance, which allows updating by the login user while providing the web-server with the required permissions.
  28
  29 The below makes the following assumptions, **you will need to change these parts** of the commands to make it work for you:
  30
  31 - Your normal login user (That you may run updates with) is called `barry`.
  32 - Your BookStack install folder is located at `/var/www/bookstack`.
  33 - Your web-server/php user is called `www-data` (Default on Ubuntu systems).
  34
  35 Lines starting with `#` are comments.
  36
  37 ```bash
  38 # Set the bookstack folders and files to be owned by the user barry and have the group www-data
  39 sudo chown -R barry:www-data /var/www/bookstack
  40
  41 # Set all bookstack files and folders to be readable, writable & executable by the user (barry) and
  42 # readable & executable by the group and everyone else
  43 sudo chmod -R 755 /var/www/bookstack
  44
  45 # For the listed directories, grant the group (www-data) write-access
  46 sudo chmod -R 775 /var/www/bookstack/storage /var/www/bookstack/bootstrap/cache /var/www/bookstack/public/uploads
  47
  48 # Limit the .env file to only be readable by the user and group, and only writable by the user.
  49 sudo chmod 640 /var/www/bookstack/.env
  50 ```
  51
  52 ### SELinux
  53
  54 SELinux, commonly found on RHEL-based systems, can be a factor for filesystem access in some cases.
  55 You can often check if SELinux is blocking file access by watching the relevant log while reproducing an action in BookStack
  56 which causes an error to occur, via something like the following (Ctrl+C to stop watching):
  57
  58 ```bash
  59 sudo tail -f /var/log/audit/audit.log
  60 ```
  61
  62 Alternatively you could temporarily disable SELinux to check if any issues are resolved with SELinux inactive.
  63 If SELinux appears to be the problem, you may additionally need to add a type label to your install files.
  64 The below commands show an example of applying SElinux labels on a BookStack installation.
  65
  66 The below makes the following assumptions, **you will need to change these parts** of the commands to make it work for you:
  67
  68 - Your BookStack install folder is located at `/var/www/bookstack`.
  69 - Your web-server uses the `httpd_sys_content_t` for readonly files and `httpd_sys_rw_content_t` for read-write files.
  70
  71 Lines starting with `#` are comments.
  72
  73 ```bash
  74 # Set the httpd_sys_content_t type on all bookstack files
  75 semanage fcontext -a -t httpd_sys_content_t    '/var/www/bookstack(/.*)?'
  76
  77 # Set the httpd_sys_rw_content_t type on all directories that will need need read-write access
  78 semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/bookstack/storage(/.*)?'
  79 semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/bookstack/bootstrap/cache(/.*)?'
  80 semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/bookstack/public/uploads(/.*)?'
  81
  82 # Apply the changes
  83 restorecon -R /var/www/bookstack
  84 ```