Summary

Sometimes it is necessary to collect Bitbucket logs - application, access, or auditing - and transfer them to a central log-collecting software for storage and analysis. Usually, this type of software uses agents installed on the Bitbucket Linux nodes; those agents read the log files and transfer the contents to the central location.

• One example of such software is Splunk. It uses Splunk agents installed on Bitbucket Data Center nodes to collect log files.

For security reasons, no general software - Bitbucket and log collecting agents included - should run as a Linux "root" user. It is common to have a separate Linux "service account" for every piece of software - for Bitbucket that one may be "atlbitbucket"; log collecting agents would have some other, separate Linux service account.

To make two separate service accounts able to access the same set of log files - written by "atlbitbucket", and read by some other account, some Linux user group membership or file system permissions tuning is required.

Environment

The solution has been validated in Bitbucket 8.19.3 but may be applicable to other versions.

Solution

The examples below are given with the Splunk agent in mind, but the same approach should be followed with other types of log-collecting software. However, you will need to alter examples depending on the Linux service account usernames and groups, and provide actual directory paths.

There are two possibilities to allow external agents to read the log files.

Option 1: add the external agent's user to the Bitbucket's group

The first option is to add the Linux user used to run the external agent to Bitbucket's Linux user group.
Group ownership of the Bitbucket log directory and files are already set to that group. Adding the external agent to that same group will allow it to read the group-owned files if they have the "group readable" bit set, which, by default, they do.

For example, if the log files group ownership is "users", the steps would be:

1. Determine the username external log collector agent runs as.
2. Stop the external agent.
3. Add the external agent's username to the Unix group "users" - the actual command may differ on your Linux distribution; on Debian/Ubuntu systems, this should work:
   

   adduser <external_agent_username> users
   
   

    Replace "users" with the group name shown on the Bitbucket log files; check with the ls -l command.

4. Ensure the permissions of directories with log files are set to 750.
   Check them using ls -l and use chmod 750 ...  to change them if needed.
5. Start the external log collector agent.
6. Check if it works as expected.

Option 2: Change group ownership of the log directories and use Set-GID on them

The other option is to force files written to the log directories to be group-owned by the specific, non-default group - for example, to be group-owned by the group "splunk", or whatever the group external agent runs as. You can also choose to add a completely new group, and add both external agent and the Bitbucket to that one. In the example below, we'll use the name "splunkgroup" for the group name.

The steps to achieve this are given below; please change the directory paths, user names, and group names according to your setup!

1. Ensure the permissions of the log directories are set to 750.
   Use ls -l to check them and chmod 750 ... to alter them if needed.

2. Add the new group, if necessary:
   

   # addgroup splunkgroup
   info: Selecting GID from range 1000 to 59999 ...
   info: Adding group `splunkgroup' (GID 1001) ...
    

3. Add the Bitbucket user to that group:
   

   # adduser bitbucket splunkgroup
   info: Adding user `bitbucket' to group `splunkgroup' ...
   

   
   

4. If you created a new group, add the external agent's username to that group, too:
   

   # adduser <external_agent_username> splunkgroup
   info: Adding user `<external_agent_username>' to group `splunkgroup' ...

5. Check the group memberships of the Bitbucket user:
   

   # groups bitbucket
   bitbucket : bitbucket splunkgroup
   

6. If you added the external agent to the new group, check the group memberships of the Splunk agent's user.
   

   # groups <external_agent_username>
   bitbucket : ... splunkgroup
   

7. Change group ownership and add Set-GID permission on the log directory:
   

   # cd <BITBUCKET_HOME>
   # ls -ld log/
   drwxr-x--- 2 bitbucket bitbucket 4096 Feb 10 13:09 log/
   
   # chgrp splunkgroup log
   # chmod g+s log
   
   # ls -ld log/
   drwxr-s--- 2 bitbucket splunkgroup 4096 Feb 10 13:09 log/
    

   
   

8. Change the group ownership of the existing files inside the log directory:
   

   # ls -l log/
   total 248
   -rw-r----- 1 bitbucket bitbucket 253147 Feb 10 13:09 atlassian-bitbucket.log
   
   # chgrp splunkgroup log/*
   
   # ls -l log/
   total 248
   -rw-r----- 1 bitbucket splunkgroup 253147 Feb 10 13:09 atlassian-bitbucket.log
    

9. Restart Bitbucket for the new group membership to be applied.
10. If you added the external agent to the new group, restart it too for the new group membership to be applied.
11. Check if it works as expected.

Other notes

• It is advisable to have an "x" attribute set on directories in addition to "r".
  Without it, applications may have issues reading the directory's contents —"x" for directory means "be able to list the contents of this directory."
• Unless the file is really an executable file, never set the "x" flag on the file.