8000 Merge branch '4.4' into 5.1 · symfony/symfony-docs@f482a94 · GitHub
[go: up one dir, main page]
Skip to content

Commit f482a94

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '4.4' into 5.1
* 4.4: Readded ACL file permission docs
2 parents 385a239 + ff086e9 commit f482a94

File tree

1 file changed

+93
-16
lines changed

1 file changed

+93
-16
lines changed

‎setup/file_permissions.rst

Lines changed: 93 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,96 @@
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! Since 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+
Symfony generates certain files in the ``var/`` directory of your project when
5+
running the application. In the ``dev`` :ref:`environment <configuration-environments>`,
6+
the ``bin/console`` and ``public/index.php`` files use ``umask()`` to make sure
7+
that the directory is writable. This means that you don't need to configure
8+
permissions when developing the application in your local machine.
9+
10+
However, using ``umask()`` is not considered safe in production. That's why you
11+
often need to configure some permissions explicitly in your production servers
12+
as explained in this article.
13+
14+
Permissions Required by Symfony Applications
15+
--------------------------------------------
16+
17+
These are the permissions required to run Symfony applications:
18+
19+
* The ``var/log/`` directory must exist and must be writable by both your
20+
web server user and the terminal user;
21+
* The ``var/cache/`` directory must be writable by the terminal user (the
22+
user running ``cache:warmup`` or ``cache:clear`` commands);
23+
* The ``var/cache/`` directory must be writable by the web server user if you use
24+
a :doc:`filesystem-based cache </components/cache/adapters/filesystem_adapter>`.
25+
26+
.. _setup-file-permissions:
27+
28+
Configuring Permissions for Symfony Applications
29+
------------------------------------------------
30+
31+
On Linux and macOS systems, if your web server user is different from your
32+
command line user, you need to configure permissions properly to avoid issues.
33+
There are several ways to achieve that:
34+
35+
1. Using ACL on a System that Supports ``setfacl`` (Linux/BSD)
36+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
37+
38+
Using Access Control Lists (ACL) permissions is the most safe and
39+
recommended method to make the ``var/`` directory writable. You may need to
40+
install ``setfacl`` and `enable ACL support`_ on your disk partition before
41+
using this method. Then, use the following script to determine your web
42+
server user and grant the needed permissions:
43+
44+
.. code-block:: terminal
45+
46+
$ 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)
47+
# if this doesn't work, try adding `-n` option
48+
49+
# set permissions for future files and folders
50+
$ sudo setfacl -dR -m u:"$HTTPDUSER":rwX -m u:$(whoami):rwX var
51+
# set permissions on the existing files and folders
52+
$ sudo setfacl -R -m u:"$HTTPDUSER":rwX -m u:$(whoami):rwX var
53+
54+
Both of these commands assign permissions for the system user (the one
55+
running these commands) and the web server user.
56+
57+
.. note::
58+
59+
``setfacl`` isn't available on NFS mount points. However, storing cache and
60+
logs over NFS is strongly discouraged for performance reasons.
61+
62+
2. Use the same User for the CLI and the Web Server
63+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
64+
65+
Edit your web server configuration (commonly ``httpd.conf`` or ``apache2.conf``
66+
for Apache) and set its user to be the same as your CLI user (e.g. for Apache,
67+
update the ``User`` and ``Group`` directives).
68+
69+
.. caution::
70+
71+
If this solution is used in a production server, be sure this user only has
72+
limited privileges (no access to private data or servers, execution of
73+
unsafe binaries, etc.) as a compromised server would give to the hacker
74+
those privileges.
75+
76+
3. Without Using ACL
77+
~~~~~~~~~~~~~~~~~~~~
78+
79+
If none of the previous methods work for you, change the ``umask`` so that the
80+
cache and log directories are group-writable or world-writable (depending
81+
if the web server user and the command line user are in the same group or not).
82+
To achieve this, put the following line at the beginning of the ``bin/console``,
83+
and ``public/index.php`` files::
84+
85+
umask(0002); // This will let the permissions be 0775
86+
87+
// or
88+
89+
umask(0000); // This will let the permissions be 0777
90+
91+
.. caution::
92+
93+
Changing the ``umask`` is not thread-safe, so the ACL methods are recommended
94+
when they are available.
95+
96+
.. _`enable ACL support`: https://help.ubuntu.com/community/FilePermissionsACLs

0 commit comments

Comments
 (0)
0