A netrc file (.netrc or _netrc) is used to hold credentials necessary to login to your LabKey Server and authorize access to data stored there. The netrc file contains configuration and autologin information for the FTP (File Transfer Protocol) client and other programs. It may be used when working with SAS Macros, Transformation Scripts in Java or using the Rlabkey package.

Set Up a Netrc File

On a Mac, UNIX, or Linux system the netrc file should be named .netrc (dot netrc) and on Windows it should be named _netrc (underscore netrc). The file should be located in your home directory and the permissions on the file must be set so that you are the only user who can read it, i.e. it is unreadable to everyone else. It should be set to at least Read (400), or Read/Write (600).

To create the netrc on a Windows machine, first create an environment variable called ’HOME’ that is set to your home directory (for example, c:/Users/<User-Name>) or any directory you want to use.

In that directory, create a text file with the prefix appropriate to your system, either an underscore for windows or dot for other systems.

The following three lines must be included in the file. The lines must be separated by either white space (spaces, tabs, or newlines) or commas:

machine <instance-of-labkey-server>
login <user-email>
password <user-password>

One example would be:

machine mymachine.labkey.org
login user@labkey.org
password mypassword

Another example would be:

machine mymachine.labkey.org login user@labkey.org password mypassword

Avoid leaving extra newlines at the end of your netrc file. Some applications may interpret these as missing additional entries or premature EOFs.

Use API Keys

When API Keys are enabled on your server, you can generate a specific token representing your login credentials on that server and use it in the netrc file. The "login" name used is "apikey" (instead of your email address) and the unique API key generated is used as the password. See API Keys for more information and examples.

Provide Alternative Location for Netrc

If you need to locate your netrc file somewhere other than the default location (such as to enable a dockerized scripting engine) you can specify the location in your code.

In Rlabkey, you could use labkey.setCurlOptions:

Rlabkey::labkey.setCurlOptions(NETRC_FILE = '/path/to/alternate/_netrc')

In Python, you can set CURLOPT_NETRC_FILE:

curl_easy_setopt(curl, CURLOPT_NETRC_FILE, "/path/to/alternate/_netrc");


If you receive "unauthorized" error messages when trying to retrieve data from a remote server you should first check that:

  1. Your netrc file is configured correctly, as described above
  2. You have an entry for that remote machine
  3. The login credentials are correct.
Additional troubleshooting assistance is provided below.

Port Independence

Note that the netrc file only deals with connections at the machine level and should not include a port or protocol designation, meaning both "mymachine.labkey.org:8888" and "https://mymachine.labkey.org" are incorrect.

If you see an error message similar to "Failed connect to mymachine.labkey.org:443; Connection refused", remove the port number from your netrc machine definition.

File Location

An error message similar to "HTTP request was unsuccessful. Status code = 401, Error message = Unauthorized" could indicate an incorrect location for your netrc file. In a typical installation, R will look for libraries in a location like \home\R\win-library. If instead your installation locates libraries in \home\Documents\R\win-library, for example, then the netrc file would need to be placed in \home\Documents instead of the \home directory.

Related Topics


Was this content helpful?

Log in or register an account to provide feedback

expand all collapse all