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)
library(RCurl)
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 "DOMAIN.org" with your server:
library(Rlabkey)
cat("\n\n\nAttempt a connection to DOMAIN.org using only RCurl. If it works, print first 200 characters of website. \n")
y = getURLContent("https://DOMAIN.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 OSX:
openssl s_client -showcerts -connect DOMAIN.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
Syntax Change from . to _
The syntax for arguments to setCurlOptions has changed. If you see an error like this:
Error in labkey.setCurlOptions(ssl.verifypeer = FALSE, ssl.verifyhost = FALSE) :
The legacy config : ssl.verifyhost is no longer supported please update to use : ssl_verifyhost
Execution halted
Use the arguments set_verifypeer and set_verifyhost instead.
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. Learn more in this troubleshooting section:
(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 OSX 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 Authentication
Rlabkey functions can be authenticated using an API key or username and password, either via a netrc file or using labkey.setDefaults() to set both username and password. Update to Rlabkey version 2.3.4, available on CRAN.
API keys, or session keys tied to a single browser session, must be enabled on your server by an administrator. When a key is generated and then used in Rlabkey, it will be used to authenticate operations based on the access available to the user who generated the key at the time the key was generated.
If an API key is not provided, the labkey.setDefaults() function can be used for basic email/password authentication. Both must be set simultaneously. Note that if both an apikey and a username/password combination are supplied, the apikey will take precendence and the username and password will be ignored.
Learn more:
Related Topics