Summary of Steps:
- Copy the tnsnames.ora file to a location the tableau user has access to
- Set permissions on the file.
- Update the environment TNS_ADMIN variable, if needed, to point to the directory from step (1).
Step 1: Copy the tnsnames.ora file to a directory the unprivileged user (tableau) can access
For versions 2019.3.x and up:
Copy the tnsnames.ora file to the /etc directory.
For versions 2019.2.x and earlier:
By default, the unprivileged user is named 'tableau'. All Tableau Server processes are run with this account, and it must be able to locate the tnsnames.ora file to use it.
If you have already installed the Oracle connector, we recommend you copy the file to the directory /opt/tableau/tableau_driver/oracle.
You can confirm that the directory is accessible by the user by using 'su' to change to the account and changing to the directory. For example:
sudo su tableau
If these steps result in a 'permission denied' error, you need to update the permissions on the directory you are using.
Step 2: Set permissions for the tnsnames.ora file
2019.2.x and earlier, follow the steps below:
- Navigate to the file path where the tnsnames.ora file is located.
- Grant permissions to the file by running the command: chmod 666 tnsnames.ora
- Verify file permissions with the following command: ls -l
The environment path should not
have a trailing slash. If the format of the path is incorrect, users may encounter an ORA-12154 error.2019.3 and later:
As tabsvc is no longer present on Linux, the above steps are no longer applicable. Instead, place the tsnames.ora file in the /etc
directory on the Linux machine. No environmental variable is necessary.2020.2 and later:
Create an /opt/tableau/tableau_driver/jdbc/oracle.properties file (create the containing folder if it doesn't already exist) with below text:
Change the /etc
if necessary to point to the path of the tnsnames.ora file within the file system.
Further information regarding JDBC properties files may be found here: https://kb.tableau.com/articles/howto/Customizing-JDBC-Connections
Step 3: Set the TNS_ADMIN environment variable to point to the directory from step (1)
For versions 2019.3.x and up: you can skip this step; no environment variable is required.
For versions 2019.2.x and earlier:
- In a text editor, open the file that matches your version of Tableau Server:
- Tableau Server 10.5.x -- /etc/systemd/system/tabsvc_0.service
- Tabelau Server 2018.1.x - 2019.2 -- /var/opt/tableau/tableau_server/.local/share/systemd/user/tabsvc_0.service
- Add the following line, where "/path/to/file-folder" is the directory you copied tnsnames.ora to in step 1:
- Save the changes to the file.
Note: The environment path should not have a trailing slash; if the format of the path is incorrect, users may encounter an ORA-12154 error.
Finding tnsnames.ora files
If the Oracle client is installed on your server, the tnsnames.ora file will be located in the following directory: $ORACLE_HOME/network/admin.
You can verify if this file exists with the following commands:
will print the file path.
sudo find / -iname tnsnames.ora
will list the locations of any tnsnames.ora files in your file system.
Note: It is not necessary to have the Oracle client installed to use tnsnames.ora with Tableau Server. This step is simply to help you work with any existing installation.
Creating new tnsnames.ora file from scratch
If no tnsnames.ora file is present on this computer, and you do not have one to copy up from a client workstation, you can create one using a text editor. Keep in mind the following restrictions:
The tnsnames.ora file name is case sensitive, and must be in all lower-case letters.
The file should not use tab-spacing.
Below is a potential template for an entry. Elements in brackets must be replaced by values obtained from your database administrator.
Note: Although a TNSNames.ora file on a Windows or Mac computer may not require the ADDRESS_LIST entry, the tnsnames.ora file on a Linux computer requires this variable.
(ADDRESS = (PROTOCOL = TCP)(HOST = prod.corp.com)(PORT = 1521)
(SERVICE_NAME = orcl)
Note: If you have SSL configured on Oracle, see additional steps below.