This topic provides basic diagnostic tests and solutions to common connection errors related to configuring the Rlabkey package to work with LabKey Server.

Diagnostic Tests

Check Basic Installation Information

The following will gather basic information about the R configuration on the server. Run the following in an R view. To create an R view: from any data grid, select Report > Create R Report.

library(Rlabkey)
cat("Output of SessionInfo \n")
sessionInfo()
cat("\n\n\nOutput of Library Search path \n")
.libPaths()

This will output important information such as the version of R being run, the version of each R library, the Operating System of the server, and the location of where the R libraries are being read from.

Check that your are running a modern version of R, and using the latest version of Rlabkey (2.1.129) and RCurl. If anything is old, we recommend that you update the packages.

Test HTTPS Connection

The following confirms that R can make a HTTPS connection to known good server. Run the following in an R View:

library(Rlabkey)
cat("\n\nAttempt a connection to Google. If it works, print first 200 characters of website. \n")
x = getURLContent("https://www.google.com")
substring(x,0,200)

If this command fails, then the problem is with the configuration of R on your server. If the server is running Windows, the problem is most likely that their are no CA Certs defined. You will need to fix the configuration of R to ensure a CA Certificate is defined. Use the RLABKEY_CAINFO_FILE environment variable. See http://finzi.psych.upenn.edu/library/Rlabkey/html/labkey.setCurlOptions.html

Diagnose RCurl or Rlabkey

Next check if the problem is coming from the RCurl library or the Rlabkey library. Run the following in an R View, replacing "labkey.org" with your server:

library(Rlabkey)
cat("\n\n\nAttempt a connection to labkey.org using only RCurl. If it works, print first 200 characters of website. \n")
y = getURLContent("https://labkey.org:8443")
substring(y,0,200)

If this command fails, it means there is a problem with the SSL Certificate installed on the server.

Certificate Test

The 4th test is to have R ignore any problems with certificate name mis-matches and certificate chain integrity (that is, using a self-signed certificate or the certificate is signed by a CA that the R program does not trust. In an R view, add the following line after library(Rlabkey)

labkey.setCurlOptions(ssl.verifypeer=FALSE, ssl.verifyhost=FALSE)

If this command fails, then there is a problem with the certificate. A great way to see the information on the certificate is to run the following from Linux or MacOSX

openssl s_client -showcerts -connect labkey.org:8443

This will show all certificates in the cert chain and whether they are trusted. If you see verify return:0 near the top of the output then the certificate is good.

Common Issues

TLSv1 Protocol Replaces SSLv3

By default, Rlabkey will connect to LabKey Server using the TLSv1 protocol. If your attempt to connect fails, you might see an error message similar to one of these:

Error in function (type, msg, asError = TRUE) : 
error:1408F10B:SSL routines:SSL3_GET_RECORD:wrong version number

Error in function (type, msg, asError = TRUE) : 
error:1411809D:SSL routines:SSL_CHECK_SERVERHELLO_TLSEXT:tls invalid ecpointformat list

First confirm that you are using the latest versions of Rlabkey and rCurl, both available on CRAN.

If you still encounter this issue, you can add the following to your R scripts or R session. This command tells R to use the TLSv1+ protocol (instead of SSLv3) for all connections:

labkey.setCurlOptions(sslversion=1)

Tomcat GET Header Limit

By default, Tomcat sets a size limit of 4096 bytes (4 KB) for the GET header. If your API calls hit this limit, you can increase the default header size for GETs.

To increase the allowable header size, edit Tomcat's server.xml file, adding a maxHttpHeaderSize attribute to the Connector entries. (By default, if this attribute is not present, the default value is set to 4096 bytes.) For example, to increase the size to 64KB:

<Connector port="8080" maxHttpHeaderSize="65536"...

(Windows) Failure to Connect

Rlabkey uses the package RCurl to connect to the LabKey Server. On Windows, older versions of the RCurl package are not configured for SSL by default. In order to connect, you may need to perform the following steps:

1. Create or download a "ca-bundle" file.

We recommend using ca-bundle file that is published by Mozilla. See http://curl.haxx.se/docs/caextract.html. You have two options:

2. Copy the ca-bundle.crt file to a location on your hard-drive.

If you will be the only person using the Rlabkey package on your computer, we recommend that you

  • create a directory named `labkey` in your home directory
  • copy the ca-bundle.crt into the `labkey` directory
If you are installing this file on a server where multiple users will use may use the Rlabkey package, we recommend that you
  • create a directory named `c:\labkey`
  • copy the ca-bundle.crt into the `c:\labkey` directory
3. Create a new Environment variable named `RLABKEY_CAINFO_FILE`

On Windows 7, Windows Server 2008 and earlier

  • Select Computer from the Start menu.
  • Choose System Properties from the context menu.
  • Click Advanced system settings > Advanced tab.
  • Click on Environment Variables.
  • Under System Variables click on the new button.
  • For Variable Name: enter RLABKEY_CAINFO_FILE
  • For Variable Value: enter the path of the ca-bundle.crt you created above.
  • Hit the Ok buttons to close all the windows.
On Windows 8, Windows 2012 and above
  • Drag the Mouse pointer to the Right bottom corner of the screen.
  • Click on the Search icon and type: Control Panel.
  • Click on -> Control Panel -> System and Security.
  • Click on System -> Advanced system settings > Advanced tab.
  • In the System Properties Window, click on Environment Variables.
  • Under System Variables click on the new button.
  • For Variable Name: enter RLABKEY_CAINFO_FILE
  • For Variable Value: enter the path of the ca-bundle.crt you created above.
  • Hit the Ok buttons to close all the windows.
Now you can start R and begin working.

Self-Signed Certificate Authentication

If you are using a self-signed certificate, and connecting via HTTPS on a Mac or Linux machine, you may see the following issues as Rlabkey attempts unsuccessfully to validate that certificate.

Peer Verification

If you see an error message that looks like the following, you can tell Rlabkey to ignore any failures when checking if the server's SSL certificate is authentic.

> rows <- labkey.selectRows(baseUrl="https://SERVERNAME", folderPath="home",schemaName="lists", queryName="myFavoriteList") 
Error in function (type, msg, asError = TRUE) :
SSL certificate problem, verify that the CA cert is OK. Details:
error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed

To bypass the peer verification step, add the following to your script:

labkey.setCurlOptions(ssl.verifypeer=FALSE)

Certificate Name Conflict

It is possible to tell Rlabkey to ignore any failures when checking if the server's name used in baseURL matches the one specified in the SSL certificate. An error like the following could occur when the name on the certificate is different than the SERVERNAME used.

> rows <- labkey.selectRows(baseUrl="https://SERVERNAME", folderPath="home",schemaName="lists", queryName="ElispotPlateReader") 
Error in function (type, msg, asError = TRUE) :
SSL peer certificate or SSH remote key was not OK

To bypass the host verification step, add the following to your script:

labkey.setCurlOptions(ssl.verifyhost=FALSE)

Troubleshoot .netrc / _netrc Files

For details see: Create a .netrc or _netrc file

Discussion

previousnext
 
expand all collapse all