10000 minor #14327 [Set-up] Readded ACL file permission docs (wouterj) · symfony/symfony-docs@0aaf00d · GitHub
[go: up one dir, main page]
Skip to content

Commit 0aaf00d

Browse files
javiereguiluzjaviereguiluz
committed
minor #14327 [Set-up] Readded ACL file permission docs (wouterj)
This PR was merged into the 4.4 branch. Discussion ---------- [Set-up] Readded ACL file permission docs We dropped all this documentation because Symfony 4.0 came with a great improvement on this topic - using `umask` in dev environments. However, setting up file permissions is still required in non-dev environments when Symfony has to dynamically write to the `var` directory (e.g. logs or file-based cache, including doctrine query result cache). Currently, the docs say "One way this can be done is by using ``chmod -R 777 var/log/``.", I would argue that this is the worst method to fix the file permissions. That's why I readded the ACL documentation used in 3.4 (I've often visited this page in 3.4 to get copy/past the command for new applications). I've made a couple changes from the 3.4 version: * I've reordered to put the most recommended method (ACL) as first; * I've dropped macOS. Both these commands a very much 90% use-case fit commands, so they were a bit maintenance heavy - which means I wanted to reduce the list. I don't think many people run Symfony in production on a macOS server. See e.g. symfony/demo#795 (comment) for a issue report about this problem in Symfony 4+. Commits ------- 0553891 Readded ACL file permission docs
2 parents 16550e7 + 0553891 commit 0aaf00d

File tree

1 file changed

+97
-16
lines changed

1 file changed

+97
-16
lines changed

‎setup/file_permissions.rst

Lines changed: 97 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,100 @@
11
Setting up or Fixing File Permissions
22
=====================================
33

4-
In Symfony 3.x, you needed to do some extra work to make sure that your cache directory
5-
was writable. But that is no longer true! In Symfony 4, everything works automatically:
6-
7-
* In the ``dev`` environment, ``umask()`` is used in ``bin/console`` and ``public/index.php``
8-
so that any created files are writable by everyone.
9-
10-
* In the ``prod`` environment (i.e. when ``APP_ENV`` is ``prod`` and ``APP_DEBUG``
11-
is ``0``), as long as you run ``php bin/console cache:warmup``, no cache files
12-
will need to be written to disk at runtime. The only exception is when using
13-
a filesystem-based cache, such as Doctrine's query result cache or Symfony's
14-
cache with a filesystem provider configured.
15-
16-
* In all environments, the log directory (``var/log/`` by default) must exist
17-
and be writable by your web server user and terminal user. One way this can
18-
be done is by using ``chmod -R 777 var/log/``. Be aware that your logs are
19-
readable by any user on your production system.
4+
The ``var/`` directory in a Symfony application is used to store generated
5+
files (cache and logs) and file-based cache files. In the production
6+
environment, you often need to add explicit permissions to let Symfony
7+
write files into this directory.
8+
9+
.. tip::
10+
11+
In dev environments, ``umask()`` is used in ``bin/console`` and
12+
``public/index.php`` to make sure the directory is writable. However,
13+
this is not a safe method and should not be used in production.
14+
15+
Setting up File Permissions in Production
16+
-----------------------------------------
17+
18+
This section describes the required permissions. See
19+
:ref:`the next section <setup-file-permissions>` on how to add the
20+
permissions.
21+
22+
* The ``var/log/`` directory must exist and must be writable by both your
23+
web server user and the terminal user;
24+
* The ``var/cache/`` directory must be writable by the terminal user (the
25+
user running ``cache:warmup`` or ``cache:clear``). It must also be writable
26+
by the web server user if you're using the
27+
:doc:`filesystem cache provider </components/cache/adapters/filesystem_adapter>`;
28+
or Doctrine query result cache.
29+
30+
.. _setup-file-permissions:
31+
32+
Configuring File Permissions on Linux and macOS System
33+
------------------------------------------------------
34+
35+
On Linux and macOS systems, if your web server user is different from your
36+
command line user, you need to configure permissions properly to avoid issues.
37+
There are several ways to achieve that:
38+
39+
1. Using ACL on a System that Supports ``setfacl`` (Linux/BSD)
40+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
41+
42+
Using Access Control Lists (ACL) permissions is the most safe and
43+
recommended method to make the ``var/`` directory writable. You may need to
44+
install ``setfacl`` and `enable ACL support`_ on your disk partition before
45+
using this method. Then, use the following script to determine your web
46+
server user and grant the needed permissions:
47+
48+
.. code-block:: terminal
49+
50+
$ HTTPDUSER=$(ps axo user,comm | grep -E '[a]pache|[h]ttpd|[_]www|[w]ww-data|[n]ginx' | grep -v root | head -1 | cut -d\ -f1)
51+
# if this doesn't work, try adding `-n` option
52+
53+
# set permissions for future files and folders
54+
$ sudo setfacl -dR -m u:"$HTTPDUSER":rwX -m u:$(whoami):rwX var
55+
# set permissions on the existing files and folders
56+
$ sudo setfacl -R -m u:"$HTTPDUSER":rwX -m u:$(whoami):rwX var
57+
58+
Both of these commands assign permissions for the system user (the one
59+
running these commands) and the web server user.
60+
61+
.. note::
62+
63+
``setfacl`` isn't available on NFS mount points. However, storing cache and
64+
logs over NFS is strongly discouraged for performance reasons.
65+
66+
2. Use the same User for the CLI and the Web Server
67+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
68+
69+
Edit your web server configuration (commonly ``httpd.conf`` or ``apache2.conf``
70+
for Apache) and set its user to be the same as your CLI user (e.g. for Apache,
71+
update the ``User`` and ``Group`` directives).
72+
73+
.. caution::
74+
75+
If this solution is used in a production server, be sure this user only has
76+
limited privileges (no access to private data or servers, execution of
77+
unsafe binaries, etc.) as a compromised server would give to the hacker
78+
those privileges.
79+
80+
3. Without Using ACL
81+
~~~~~~~~~~~~~~~~~~~~
82+
83+
If none of the previous methods work for you, change the ``umask`` so that the
84+
cache and log directories are group-writable or world-writable (depending
85+
if the web server user and the command line user are in the same group or not).
86+
To achieve this, put the following line at the beginning of the ``bin/console``,
87+
``web/app.php`` and ``web/app_dev.php`` files::
88+
89+
umask(0002); // This will let the permissions be 0775
90+
91+
// or
92+
93+
umask(0000); // This will let the permissions be 0777
94+
95+
.. caution::
96+
97+
Changing the ``umask`` is not thread-safe, so the ACL methods are recommended
98+
when they are available.
99+
100+
.. _`enable ACL support`: https://help.ubuntu.com/community/FilePermissionsACLs

0 commit comments

Comments
 (0)
0