general

Troubleshoot Permission Issues

Introduction

Permission errors are usually associated with Linux and macOS installations. In these kinds of systems, files and directories have three operation privileges available: read (r), write (w) and execute (x). A system user can perform different operations depending on their operation privileges and the groups this user belongs to. For more information about permissions, see this guide. A permission issue occurs when an application (or system user) is performing an unauthorized operation in the filesystem.

Bitnami stacks are built with security in mind. They are configured establishing the most secure permissions without compromising the application user experience. In this sense, the standard way is the following:

  • Cloud Images and Virtual Machines:

    • Have a system user for SSH/SFTP access: bitnami
    • Have a system user and group for each daemonized process. These users will have extremely limited privileges. The reason for having multiple system users is to minimize the impact if a process' security is compromised. The following are the most common processes:
      • Apache: daemon
      • MySQL: mysql
      • PostgreSQL: postgresql
      • Tomcat: tomcat
  • The whole stack is only writable by root. By default, only read privileges are allowed for non-root users. As an exception, each daemonized process can only write to certain data folders and temporary folders. For example: mysql can write to /opt/bitnami/mysql/data and /opt/bitnami/mysql/tmp.

    • If the bitnami system user wants to edit a file, it must obtain super-user privileges. To improve user-experience, the bitnami user can have ownership (with write privileges) of certain folders (for example, WordPress htdocs folder).
  • Installers with root installation: Same as the previous case but without the bitnami user. All operations must be done by root.

  • Installers with non-root installation and Windows installers: The user that executes the installer has full ownership of the stack and all its daemonized processes.

In this how-to guide you will learn how to deal with permission errors in your application. You will learn how Bitnami configures permissions in applications, what the common issues are, and some guidelines about how to fix issues in the stack.

How to detect

Detecting permission issues is quite straightforward. It usually implies an application crashing or showing errors (either in the logs or in the standard output) such as the following:

Error:   [...] open for write: permission denied

Or:

[...] (errno: 13 * Permission denied)

Or:

Error: EACCES: permission denied [...]

These errors usually include the path that the process was unable to read of write.

Common issues

The following are the most common permission issues that Bitnami users face:

  • SFTP upload or file edit: Because of our secure permissions, a user cannot upload or edit files in all stack locations without super-user privileges.

  • The user modifies or changes the permissions: Either voluntarily or involuntarily, the user changes the stack’s default permissions. Because of this, the application stops working. A subset of this kind of cases is that of a manual upgrade issues.

  • Operation performed by the wrong system user: This mainly applies to the stacks that have command line utilities (such as Magento or ERPNext). If the user executes a command-line operation, an error may occur because the operation was executed by the wrong system user. Depending on this system user’s privileges, the stack can become unusable.

  • Plugin incompatibility: Some plugins require specific permissions for certain configuration files (for example wp-config.php in WordPress). These permissions can be incompatible with the ones Bitnami set by default.

Troubleshooting checklist

The following checklist covers the majority of cases described above. You can find and debug most permission issues.

Are you using the proper program to edit permissions?

FTP clients such as Filezilla cannot be used to modify the permissions in your stack. Instead, you should use a SSH client. To learn more about connecting through SSH, see this guide.

You can’t upload a file via SFTP?

If you see an error like this when uploading a file:

[...] permission denied

Temporarily change the permissions of the destination folder or file, upload the files, and then restore the file or folder to its original state. To do this, follow the steps below:

  • Log in to the server console. Learn how to connect to the server through SSH.

  • Execute the command in the target folder where you want to upload the file to (replace TARGETFOLDER with the proper path):

      $ sudo stat TARGETFOLDER
    

    If you want to upload a file, replace the TARGETFOLDER placeholder with the full path to the file. The following is an example:

      $ sudo stat /opt/bitnami/apps/wordpress/htdocs/wp-config.php
    
  • You will see an output like this:

      Access: (0775/drwxrwxr-x)  Uid: ( 1000/ daemon)   Gid: (    1/  daemon)
    
  • Take a note of this information. In this case, the file or folder has the following permissions:

    • Permissions: 0775
    • Owner: daemon
    • Group: daemon
  • Change the owner of the folder or file to bitnami (remember to replace the TARGETFOLDER placeholder with the proper path):

      $ sudo chown bitnami TARGETFOLDER
      $ sudo chmod +w TARGETFOLDER
    
  • You should now be able to upload files to the folder or replace the file. When you are finished, restore the original permissions. For the case above, the commands are as follows:

      $ sudo chown daemon:daemon TARGETFOLDER
      $ sudo chmod 0775 TARGETFOLDER
    

You can’t edit a file via SSH?

If you are getting an error like this when trying to edit a file inside your SSH session:

[...] permission denied

You must edit the file with superuser privileges. Execute the command in the file you want to edit (replace TARGETFILE with the proper path). In this example we will use nano as the editor:

$ sudo nano TARGETFILE

The saved file should maintain the original privileges.

Are the permissions in your stack set properly?

If your application crashes or shows an error like the following:

[...] permission denied

It is probable that the permissions in the stack are incorrect. These situations are normally due to a manual change in the permissions of the application.

  • Check the command history for permission change operations:

      $ history
    
  • Check the output. Examples of this kind of operation are as follows:

      $ sudo chown bitnami:bitnami -R /opt/bitnami/apps/magento/htdocs/
      $ sudo chmod 777 -R /opt/bitnami/apps/magento/htdocs/
    
  • If you do not find anything suspicious, then create an issue in this github repository following the guidelines.

  • Look at the original application configuration (you can launch a new fresh cloud instance of the application). Check the writable folders and check that the permissions are correct. The following is an example of Magento’s writable folders:

      $ ls /opt/bitnami/apps/magento/htdocs/var/cache/ -la
      total 76
      drwxrwsrwx 19 bitnami bitnami 4096 Oct 26 12:17 .
      drwxrwsrwx  7 bitnami bitnami 4096 Oct 26 15:28 ..
      drwxrwxrwx  2 bitnami bitnami 4096 Oct 26 12:17 mage--0
      drwxrwxrwx  2 bitnami bitnami 4096 Oct 26 15:15 mage--1
      drwxrwxrwx  2 bitnami bitnami 4096 Oct 26 12:19 mage--2
      drwxrwxrwx  2 bitnami bitnami 4096 Oct 26 12:17 mage--3
      drwxrwxrwx  2 bitnami bitnami 4096 Oct 26 12:17 mage--4
      drwxrwxrwx  2 bitnami bitnami 4096 Oct 26 12:19 mage--5
      drwxrwxrwx  2 bitnami bitnami 4096 Oct 26 15:14 mage--6
    
      $ ls /opt/bitnami/apps/magento/htdocs/var/ -la
      total 44
      drwxrwsrwx  7 bitnami bitnami 4096 Oct 26 15:28 .
      drwxrwxrwx 13 bitnami bitnami 4096 Oct 18 13:45 ..
      drwxrwx--*  2 daemon  bitnami 4096 Oct 26 15:14 backups
      drwxrwsrwx 19 bitnami bitnami 4096 Oct 26 12:17 cache
      drwxrwsrwx  3 bitnami bitnami 4096 Oct 18 13:47 composer_home
      -rwxrwxrwx  1 bitnami bitnami  152 Oct 18 13:21 .htaccess
      drwxrwsrwx  2 bitnami bitnami 4096 Oct 26 12:16 log
      drwxrwsrwx  4 bitnami bitnami 4096 Oct 26 12:17 page_cache
      -rw-rw-r-*  1 daemon  bitnami 6783 Oct 26 15:28 .setup_cronjob_status
      -rwxrwxrwx  1 bitnami bitnami  148 Oct 26 15:28 .update_cronjob_status
    

    In this example we can see that the ownership is incorrect. daemon should be the owner of the files.

  • If the files' permissions are wrong, use the chmod or chown commands to restore them to their initial state. Following the example above, do the following:

      $ sudo chown daemon:daemon -R /opt/bitnami/apps/magento/htdocs/var /opt/bitnami/apps/magento/htdocs/var/cache
    
  • If your stack uses MySQL, check and reset the permissions of the MySQL data directory:

      $ sudo chown mysql:root -R /opt/bitnami/mysql/data
    
  • If your stack uses MariaDB, check and reset the permissions of the MariaDB data directory:

      $ sudo chown mysql:root -R /opt/bitnami/mariadb/data
    
  • If your stack uses Apache, reset the permissions of the Apache directory:

      $ cd /opt/bitnami
      $ sudo cp -rp ./apache{,.back}
      $ sudo chown root:root -R ./apache
      $ sudo chmod +x ./apache/bin/*
      $ sudo chmod +x ./apache/scripts/ctl.sh
      $ sudo chown bitnami:root -R ./apache/conf
      $ sudo chown root:root ...
    
  • Check if the application works without issues now.

Are you getting an error when uploading a file, upgrading or installing an extension using the application interface?

The applications are configured with the most secure, production-enabled permissions. This set of permissions should not affect the normal operation of your application. If the user interface allows file uploading, plugin installation or upgrades, these procedures should work without issues. If you find an error during one of these processes, do the following:

You can’t execute a command via SSH in the stack?

If you are trying to execute a command inside your stack and you get an error like this:

[...] permission denied

You may be executing the command as the wrong system user. To fix it, follow these instructions:

  • Load the application environment by executing the following command. Replace APPNAME with the name of your application:

      $ sudo /opt/bitnami/use_APPNAME
    

    NOTE: Replace the APPNAME placeholder with the identifier of the Bitnami application name, i.e. wordpress.

  • The command should work now without any issues.

The following resources may be of interest to you:

Last modification April 5, 2023