SMRT® Link Software Installation (v6.0.0)

Transcript

1 ® SMRT Link Software Installation (v6.0.0) Introduction on a customer system. This document This document describes the procedure for installing SMRT Link v6.0.0 is for use by Customer IT or SMRT Link Administrators. ® is the web-based end-to-end workflow manager for the Sequel SMRT Link System. It includes software applications for designing and monitoring sequencing runs, and analyzing and managing sequence data. multiple Sequel instruments. SMRT Link provides a web interface that can control for applications used by researchers, laboratory technicians, instrument SMRT Link is the primary access point with applications related to the Sequel platform. The operators, and bioinformaticians for various interactions applications include: • Sample Setup: Calculate binding and annealing reactions for pr eparing DNA samples for use on the Sequel System. Run Design : Design runs and create and/or import sample sheets which become available on the Sequel • System. • Run QC : Monitor run progress, status and quality metrics. • Data Management cess permissions for Projects and users; : Create Projects and Data Sets; manage ac t, or delete sequence, reference, and barcode files. generate QC reports for Data Sets; view, impor SMRT Analysis : Perform multiple types of secondary anal ysis, including sequence alignment, variant • de novo assembly, structural variant calling, and RNA analysis. detection, Overview 1. Install or upgrade the SMRT Link software. (See “Installation Summary” on page 5 and “Configuring LDAP” for details.) on page 23 2. ( Optional ) Configure SMRT Link to use an SSL Certificate. (See “Configuring WSO2 in SMRT Link to Use a Signed SSL Certificate” on page 27 for details.) 3. ( Optional ) Add SMRT Link Users and Assign User Roles. (See “Adding SMRT Link Users and Assigning for details.) User Roles” on page 25 Page 1

2 Data storage • The SMRT Link software must be readable and writable by the SMRT Link install user and root directory /opt/pacbio/smrtlink have the same path across all compute nodes via NFS. PacBio recommends must ), and smrtanalysis for the SMRT Link software root directory (referred to as $SMRT_ROOT for the SMRT $SMRT_USER ). Link install user (referred to as output directory is used to store output from SMRT Analysis jobs. The software • The SMRT Analysis $SMRT_ROOT/userdata/jobs_root , which can be modified accesses this directory from a symbolic link at manually or by using the install sc ript. The symbolic link destination should be on a shared file system (NFS); it must be writable by the $SMRT_USER , and it must be accessible along the same path on all compute linked to a large storage volume. nodes. This is usually symbolically database directory is used to store database fi les and backups. The software accesses • The SMRT Analysis $SMRT_ROOT/userdata/db_datadir , and it can be modified manually this directory from a symbolic link at or by using the install script. This symbolic link destination should be a directory (not NFS) and be local $SMRT_USER on the SMRT Link install host. only writable by . This directory should exist • The SMRT Analysis directory is used for fast I/O operations during run time. The software temporary accesses this directory from a symbolic link at $SMRT_ROOT/userdata/tmp_dir , and it can be modified manually or using the install script. Thi s symbolic link destination should be a local directory (not NFS), it must be writable by , and it must exist (or be creatable) as an independent directory on all $SMRT_USER compute nodes. Software Prerequisites: Server Operating Systems • SMRT Link server software is supported on English-language CentOS 6.x; 7.x and Ubuntu 14.04; 16.04 ® 64-bit Linux distributions. (This also applies to SMRT Link compute nodes.) • SMRT Link is not guaranteed to work on Linux versions that are no longer supported by the Operating Systems’ Vendors. Page 2

3 ® ® • SMRT Link server software or Windows cannot systems. be installed on macOS sites: Client Systems Software/Hardware Prerequi To use SMRT Link on a client operating system: ® Chrome web browser, version 64 or later. the Google • SMRT Link requires • SMRT Link requires a minimum screen resolution of 1600 by 900 pixels. • PacBio recommends 64-bit Java (Version 8 or later) installed on your local Windows or Mac OS host to run SMRT View. Network Configuration • Please refer to the IT Site Prep Guide provided with your instrument purchase for more details. ions, see the network diagram in the Computer Requirements section • For network connectivity considerat of the IT Site Prep Guide . vironment Assumptions SMRT Link Server En libc 2.5 or greater. • The SMRT Link server should run on a dedicated 64-bit Linux host with • Installing as the same non-root user ( $SMRT_USER ) that will be used to run the system. $SMRT_USER •The $SMRT_ROOT directory and in all linked has full permissions in the file system in the directories for jobs_root , db_datadir and tmp_dir . (Common problems include NFS setup problems, ACLs, and so on.) • When running in distributed mode, all other nodes have the same path for $SMRT_ROOT and for all linked directories. • During the installation, no other daemons/services are bound to the same ports. highly recommends that the system clock be synchroni • PacBio zed to a public NTP time server. General Security Notes research use only • SMRT Link (and the Sequel System) are for not guaranteed to be (RUO) and are secure. recommends that you install the SMRT Link server on networks that are only accessible to trusted • PacBio SMRT Link on public networks. users, and discourages installing not root as the user. •Do install SMRT Link using SMRT Link v6.0.0 Security Notes he web services API to clients running on localhost (like the WSO2 SMRT Link v6.0.0 restricts access to t server that handles authentication and permissions) or remotely using SSL encryption and password-based authentication. This change may require several post- upgrade modifications to customer environments and workflows. Ports and firewalls : Since v4.0.0 the SMRT Link GUI requires that web browsers can access the HTTPS port , which serves up the password-protected services API and static web content. This port is also used by 8243 the Sequel Instrument Control Software (ICS), so it needs to be available to Sequel instruments as well. any • If your network is already configured to leave this port open, no additional changes are required to use v6.0.0. • If you have restricted access to port 8243 to localhost (meaning the GUI can only being viewed in a browser running on the SMRT Link server itself) or specific remote hosts, exc eptions allowing the Sequel instrument(s) to access SMRT Link’s port 8243 are required . Note that the open services port, which defaults to 9091 in the installer, is no longer accessible from the exter- nal network and can be ignored or firewalled at the site administrator’s discretion. No port changes are sug- Page 3

4 gested or required as part of the SMRT Link upgrade process; the use of port 8243 not for HTTPS access is currently configurable. pbservice Command-Line Client requires authentication when used with any host other : In v6.0.0, pbservice . For most users we recommend entering the password interactively: localhost than $ pbservice status –host --user --ask-pass Password: Instrument Configuration : The accompanying Sequel ICS release is automatically configured to connect to 8243 . When you install SMRT Link v6.0.0, it creates a new pbicsuser SMRT Link at port account with a default password, which is also set in ICS. SMRT Link comes with a default Instrument Control Software (ICS) user pbicsuser communicate with SMRT Link web services account ( ) which is used by the Sequel instrument(s) to over a secure, encrypted connection. Using the default pas sword for this account may make the setup process easier, but it also makes your SMRT Link instance more susceptible to unauthorized access as this is a publicly change this default password once the instrument and known default password. We recommend that you SMRT Link have both been upgraded and confirmed working together. (Note that the pbicsuser credentials can only be used to access SMRT Link re sources – it is not a Unix shell account.) Installation/Upgrade Checklist Following is a list of items you should have ready starting a new installati on or upgrading an existing before installation: • Full path ( spaces) to the installation root directory. Used for the main installation root; see without for details. Installation Directories • Job Management System settings. • Full path ( without spaces) to a directory on the shared file system - the jobs_root directory. • Full path ( without spaces) to a directory on the local file system on each node - the tmp_dir directory. • Full path ( spaces) to a directory on the local file system on the install node - the db_datadir without directory. • (Optional) LDAP Settings. See “Configuring LDAP” on page 23 for details. “Configuring WSO2 in SMRT Link to Use a Signed SSL • (Optional) SSL Certificate for WSO2. See for details. Certificate” on page 27 Page 4

5 Installation Summary Following are the steps for installing SMRT Link v6.0.0 on a new system. (See Page 11 for sample script output , follow the upgrade steps on Page and more details.) To upgrade SMRT Link to v6.0.0 from a previous version 7. only be used with Sequel Instruments with Instrument Control Software (ICS) Note : SMRT Link v6.0.0 can v6.0.0 installed. change from a previous version of ICS should be coordinated with PacBio to ensure the Any usability of the instrument. Step Installation Summary - SMRT Link v6.0.0 Download SMRT Link software: 1 Download SMRT Link from http://www .pacb.com/support/software-downloads/. Definitions and variables: 2 For clarity, this document uses these conven tions to refer to site -specific information: $SMRT_ROOT : The SMRT Link Install Root Directory, such as /opt/pacbio/smrtlink . • $SMRT_USER • . : The SMRT Link Install User, such as smrtanlaysis smrtlinkhost.mydomain.com • : The fully-qualified domain name of the SMRT Link Install Host. • smrtlinkhost : The short host name of the SMRT Link Install Host. $SMRT_ROOT , a convenience variable can be defined in the shell so the commands below may be run For verbatim. To set the variable in the shell, use something like: SMRT_ROOT=/opt/pacbio/smrtlink The fully qualified version of SMRT Link Install Host may always be used in place of the short host name. But in some cases, particularly when working with WS O2, the fully qualified domain name is required. Log onto the SMRT Link Install Host (such as smrtlinkhost ) as the SMRT Link Install User (such as 3 $SMRT_USER ). Install SMRT Link by invoki ng the SMRT Link Installer: 4 smrtlink_6.0.0.47841.run --rootdir $SMRT_ROOT Note : The directory must not exist when the installer is invoked, as the installer will $SMRT_ROOT try to create it, and will abort the installa $SMRT_ROOT location is found. tion if an existing If a previous installation was canceled or otherwise failed, the installer can be invoked extraction. without Rerun using the --no-extract option: smrtlink_6.0.0.47841.run --rootdir $SMRT_ROOT --no-extract See for additional information. “Installation Details” on page 11 Start SMRT Li nk services: 5 $SMRT_ROOT/admin/bin/services-start Import required SMRT Link data: 6 $SMRT_ROOT/admin/bin/import-canneddata This command imports PacBio-provided data files required to run several SM RT Link analysis applications. The files include reference genome files (lambda virus geno me data for resequencing, HIV HXB2 reference for Minor Variant Analysis, and human HLA) and barcode FASTA files for demultiplexing. Note : This step is required , and must be completed after the first start of services upon a fresh installation or upgrade. Page 5

6 - SMRT Link v6.0.0 Step Installation Summary Run the Site Acceptance Test from the command line: 7 $SMRT_ROOT/admin/bin/run-sat-services Test (SAT) analysis job in the Successful completion of , which produces a Site Acceptance run-sat-services SMRT Analysis module of the SMRT Link GUI, indicates that the HPC configuration is functioning correctly. Run the Site Acceptance Test from the browser: 8 . http://smrtlinkhost:9090 1. Using the Chrome browser, open SMRT Link at – The port number should match the GUI port 9090 . The URL defined during installation; the default is 9090 will redirect to a secure URL at hard-coded port 8243 . If port is blocked, go directly to the redirect URL at https://smrtlinkhost.mydomain.com:8243/sl/ . 8243 on the SMRT Link Install Host is Check with your IT group if port – 8243 is blocked; access to port . required 2. Bypass the Chrome browser’s privacy error check: Without an SSL certificate installe d, Chrome will issue a "Privacy Error" and state that "Your connection is not private". Bypass this error by clicking on the link on the bottom left of the page. Then click on the Advanced Proceed to smrtlinkhost.mydomain.com (unsafe) link. To avoid the "Privacy Error" in the future, follow the instructions for installing th e SSL Certificate in Step 9 below. 3. Log in to SMRT Link by entering the default Administrator credentials: . admin/admin 4. Submit SMRT Link notification selections: io of successful installations and for sending ongoing SMRT Link analysis Select options for notifying PacB usage information. Click Save . Notify PacBio of the successful installation Note must be selected to enable the SMRT Link : The option send PacBio installation and analysis log files for Event Service, which enables SMRT Link users to y bundle updates, and data about software usage. troubleshooting, acceptance of new chemistr 5. Go to the SMRT Analysis page: On the SMRT Link home page ( SMRT Analysis ), click https://smrtlinkhost.mydomain.com:8243/sl/ . . + Create New Analysis 6. Create a new analysis: Click gs and start the analysis: 7. Select analysis settin a) Select from the Analysis Application drop down list, at the top left. Site Acceptance Test (SAT) field will be auto-populated with . LambdaNEB The Reference field. SMRT Link 6.0.0 SAT Test (or any descriptive name) in the b) Enter Analysis Name lambda/0007_tiny . Data Sets c) In the table, check the box next to in the top right corner to start the analysis. d) Click > Start 8. Wait for the analysis to complete successfully. On the page Analysis Results - SMRT Link 6.0.0 SAT Test ( https://smrtlinkhost.mydomain.com:8243/sl/#/analysis/job/15 ): – The spinning wheel next to the green text RUNNING on the top status bar indicates that the analysis is in progress. – The Analysis Overview page displays by default, and is updated periodically. text changes to SUCCESSFUL. – Upon success, the green RUNNING indicates that SMRT Link analysis is working Successful co mpletion of the Site Acceptance Test (SAT) and started via the browser GUI, through the SMRT Link correctly. It shows that the analysis was configured Services, and dispatched jobs to the HPC cluster (if distributed mode was configured during installation). Configure LDAP (Optional): 9 “Configuring LDAP” on page 23 for details. See for Configure SMRT Link to use a Signed SSL Certificate (Optional): 10 ® “SMRT See Link and SSL Certificate Procedures” on page 26 for details. Change the pbicsuser password: 11 pbicsuser account password in SMRT Link” on page 21 for details. See “Changing the Page 6

7 ® Upgrading SMRT Link Supported Upgrade Path must . be performed sequentially, that is: • SMRT Link upgrades 3.1.0 > 3.1.1 > 4.0.0 > 5.0.1 > 5.1.0 > 6.0.0 upgrade to SMRT Link from SMRT Analysis cannot • You v2.3.0 or earlier. Additionally, analysis job directories and run history from SMRT Analysis v2.3.0 or earlier are not compatible with SMRT Link and cannot be imported. : Notes before upgrading to admin/admin set your admin login name/ password back to the default • You must “Changing the Password for the Admin Account” on page 23 for details. v6.0.0. See only • SMRT Link v6.0.0 can be used with Sequel Instruments with Instrument Control Software (ICS) v6.0.0 installed. Any change from a previous version of ICS should be coordinated with PacBio to ensure the usability of the instrument. Step Upgrading SMRT Link Download SMRT Link software: 1 Download SMRT Link from http://www .pacb.com/support/software-downloads/. Definitions and variables: 2 tions to refer to site -specific information: For clarity, this document uses these conven $SMRT_ROOT /opt/pacbio/smrtlink . : The SMRT Link Install Root Directory, such as • $SMRT_USER : The SMRT Link Install User, such as smrtanlaysis . • • smrtlinkhost.mydomain.com : The fully-qualified domain name of the SMRT Link Install Host. • smrtlinkhost : The short host name of the SMRT Link Install Host. $SMRT_ROOT , a convenience variable can be defined in the shell so the commands below may be run For verbatim. To set the variable in the shell, use something like: SMRT_ROOT=/opt/pacbio/smrtlink The fully qualified version of SMRT Link Install Host may always be used in place of the short host name. But in some cases, particularly when working with WS O2, the fully qualified domain name is required. Log onto the SMRT Link Install Host (such as smrtlinkhost ) as the SMRT Link Install User (such as 3 ). $SMRT_USER Stop the SMRT Link services: 4 $SMRT_ROOT/admin/bin/services-stop : Notes 1. Ensure that no active SMRT Link analysi s jobs are running befo re stopping services. 2. If you have changed the default admin account password, it must be changed back to the default value of admin before proceeding. Upgrade SMRT Link by invoking the SMRT Link installer: 5 smrtlink_6.0.0.47841.run --rootdir $SMRT_ROOT --upgrade Note: The $SMRT_ROOT directory must be an existing SMRT Li nk installation. Several validation steps will occur to ensure that a valid $SMRT_ROOT is being updated. If a previous upgrade was canceled or otherw ise failed, the insta ller can be invoked without extraction. Rerun using the --no-extract option: smrtlink_6.0.0.47841.run --rootdir $SMRT_ROOT --upgrade --no-extract for additional information. See “Installation Details” on page 11 Page 7

8 Upgrading SMRT Link Step Start the SMRT Link services: 6 $SMRT_ROOT/admin/bin/services-start Import required SMRT Link data: 7 $SMRT_ROOT/admin/bin/import-canneddata This command imports PacBio-provided data files required to run several SM RT Link analysis applications. The me data for resequencing, HIV HXB2 reference for files include reference genome files (lambda virus geno Minor Variant Analysis, and human HLA) and barcode FASTA files for demultiplexing. : This step is required , and must be completed after the first start of services upon a fresh installation or Note upgrade. Run the Site Acceptance Test from the command line: 8 $SMRT_ROOT/admin/bin/run-sat-services run-sat-services , which produces a Site Acceptance Test (SAT) analysis job in the Successful completion of SMRT Analysis module of the SMRT Link GUI, indicates that the HPC configuration is functioning correctly. Page 8

9 Upgrading SMRT Link Step Run the Site Acceptance Test from the browser: 9 1. Using the Chrome browser, open SMRT Link at . http://smrtlinkhost:9090 defined during installation; the default is – The port number should match the GUI port 9090 . The URL 9090 . If port is blocked, go directly to the redirect will redirect to a secure URL at hard-coded port 8243 https://smrtlinkhost.mydomain.com:8243/sl/ URL at . – Check with your IT group if port 8243 is blocked; access to port 8243 on the SMRT Link Install Host is required . 2. Bypass the Chrome browser’s privacy error check: state that "Your connection is not Without an SSL certificate installe d, Chrome will issue a "Privacy Error" and link on the bottom left of the page. Then click on the private". Bypass this error by clicking on the Advanced link. Proceed to smrtlinkhost.mydomain.com (unsafe) To avoid the "Privacy Error" in the future, follow the instructions for installing th e SSL Certificate in Step 9 below. 3. Log in to SMRT Link by entering the default Administrator credentials: . admin/admin 4. Submit SMRT Link notification selections: Select options for notifying PacB io of successful installations and for sending ongoing SMRT Link analysis . Save usage information. Click must option Notify PacBio of the successful installation : The Note be selected to enable the SMRT Link Event Service, which enables SMRT Link users to send PacBio installation and analysis log files for troubleshooting, acceptance of new chemistr y bundle updates, and data about software usage. 5. Go to the SMRT Analysis page: On the SMRT Link home page ( ), click SMRT Analysis https://smrtlinkhost.mydomain.com:8243/sl/ . 6. Create a new analysis: Click + Create New Analysis . 7. Select analysis settin gs and start the analysis: Site Acceptance Test (SAT) from the Analysis Application drop down list, at the top left. a) Select LambdaNEB field will be auto-populated with The Reference . field. b) Enter SMRT Link 6.0.0 SAT Test (or any descriptive name) in the Analysis Name lambda/0007_tiny c) In the table, check the box next to . Data Sets d) Click > Start in the top right corner to start the analysis. page Analysis Results - SMRT Link 6.0.0 SAT Test 8. Wait for the analysis to complete successfully. On the ( ): https://smrtlinkhost.mydomain.com:8243/sl/#/analysis/job/15 – The spinning wheel next to the green text RUNNING on the top status bar indicates that the analysis is in progress. – The Analysis Overview page displays by default, and is updated periodically. text changes to SUCCESSFUL. – Upon success, the green RUNNING mpletion of the indicates that SMRT Link analysis is working Site Acceptance Test (SAT) Successful co correctly. It shows that the analysis was configured and started via the browser GUI, through the SMRT Link Services, and dispatched jobs to the HPC cluster (if distributed mode was configured during installation). Notify PacBio to u pgrade instruments: 10 fy PacBio that you have upgraded SMRT Link so that If you have a Sequel instrument, please immediately noti Technical Support can upgrad ontrol Software (ICS) for co mpatibility with SMRT Link. e the Sequel Instrument C Email [email protected] with the following message: "I have just successfully upgraded SMRT Link (UUID: uel ICS upgrade as soon as possible." xxxxxxxxxx) to 6.0.0. Please begin the Seq The SMRT Link UUID can be obtained by running the following command: cat $SMRT_ROOT/userdata/tsreport/sluuid Updating the SMRT Link Chem istry Bundle Using the GUI SMRT Link Chemistry Bundle having to reinstall the without updates allow updating of SMRT Link features ® Sequel SMRT Link software. The update also updates Instrument Control Software (ICS). Note: role can perform this update. Only SMRT Link users with the Admin Page 9

10 1. In SMRT Link, choose About from the Main menu. (A red circle indicates that a Chemistry Bundle Update is available.) 2. Click the Update button. , choose from More Tools > Clear browsing data the beginning of time 3. Clear the browser cache: Choose . Click the droplist, then check . Cached images and files Clear browsing data e for this installation of SMRT Link is updated. 4. Restart the browser. The SMRT Link Chemistry Bundl Admin 5. On the instrument, choose from the Main menu. (A red circle indicates that a Chemistry Bundle Update is available.) Updates Install . The instrument software then restarts, which will take around 10 6. Click the tab, then click minutes. try Bundle Using the Command-Line Updating the SMRT Link Chemis only if you have installed the SMRT Link package using the --smrttools-only switch. Use this procedure Download the Chemistry Bundle from the PacBio websit e, then unpack the files and place them in a user- defined directory. The value of the $SMRT_CHEMISTRY_BUNDLE_DIR environment variable then defines where the software finds the updated files. Follo wing are the suggested best practices for installing the Chemistry Bundle: http://www.pacb.com/support/software-downloads 1. Download the Chemistry Bundle from . Optional ) Define $SMRT_ROOT for convenience: 2. ( SMRT_ROOT=/opt/pacbio/smrtlink 3. Make directories, unpack, and link: mkdir -p $SMRT_ROOT/userdata/chemistry/chemistry-pb-6.0.0.xxxxx tar -C $ SMRT_ROOT/userdata/chemistry/chemistry-pb-6.0.0.xxxxx -xf /path/to/chemistry-pb- 5.1.0.xxxxx.tar.gz ln -s ./chemistry-pb-6.0.0.xxxxx $SMRT_ROOT/userdata/chemistry/chemistry-pb-active 4. Set/export $SMRT_CHEMISTRY_BUNDLE_DIR and validate: export SMRT_CHEMISTRY_BUNDLE_DIR=$SMRT_ROOT/userdata/chemistry/chemistry-pb-active 5. Set the variable in the user environment to make it permanent. Example: Use . bashrc or .bash_profile . Installing only SMRT Tools To install only command-line SMRT Tools, use the --smrttools-only option with the installation command, whether for a new installation or an upgrade. Examples: smrtlink-*.run --rootdir smrtlink --smrttools-only smrtlink-*.run --rootdir smrtlink --smrttools-only --upgrade Page 10

11 Installation Details Following is an example of the prompts that display ript, with added explanations: when running the Install sc Part 1 of 10: SMRT Analysis User PacBio recommends that you run this script ) who will as a designated SMRT Analysis user (e.g. smrtanalysis jobs and daemon processes. pbsmrtpipe own all Current user is 'smrtanalysis' (primary group: Domain Users) Use the 'smrtanalysis' as the SMRT Analysis user? [Y/n]: Using install user (computed): smrtanalysis Using install group (computed): smrtanalysis Using smrtlink uuid (computed default): 00001111-aaaa-bbbb-cccc-dddddeeeeeff Part 2 of 10: SMRT Link Server DNS The DNS name of the SMRT Link host server Link URLs (such as is used for creating SMRT ), ensuring that an SSL certificate will validate. If the Domain Name System http://smrtlink.example.com (DNS) does not resolve to the expected address, then an IP address must be used. Detecting DNS names... Pick an option: 1) smrtlinkhost.somedomain.com 2) smrtlinkhost 3) 10.1.220.142 (eth0) 4) Specify an alternate DNS name Choice [1]: Using dnsname (selected interactively): smrtlinkhost.somedomain.com Part 3 of 10: SMRT Link Setup SMRT Link requires ports for proper operation. These ports cannot be used for listening by any other pro- two from an unencrypted http connection to the login. cesses. The SMRT Link GUI port serves to redirect page using secure https. Enter the SMRT Link GUI (http) port [9090]: Enter the SMRT Link Services port [9091]: Memory settings must be preset for SMRT Link. By default, PacBio sets the initial ( -Xms ) and maximum ( -Xmx ) Java heap sizes to the same values. • The default for SMRT Link services is 25% of the total memory with a maximum of 32,768 MB. • The default for the SMRT Link GUI is 5% of the total memory with a maximum of 8,192 MB. PacBio recommends using the defaults. Enter the SMRT Link Services initial memory (in MB) [25088]: Enter the SMRT Link Services maximum memory (in MB) [25088]: Enter the SMRT Link GUI initial memory (in MB) [4992]: Enter the SMRT Link GUI maximum memory (in MB) [4992]: Using GUI port (default, accepted): 9090 Using services port (computed default, accepted): 9091 Using GUI initial memory (computed default, accepted): 4992 Using GUI maximum memory (computed default, accepted): 4992 Using services initial memory (computed default, accepted): 25088 Using services maximum memory (computed default, accepted): 25088 Page 11

12 Part 4 of 10: SMRT View Server Setup SMRT View Server requires one port for the SMRT View GUI Web server. For proper operation, this port cannot not conflict with any other pro- be used for listening by any other processes. Select a port number which does grams. Enter the SMRT View Server (http) port [9094]: Memory settings must be preset for SMRT View. By default, PacBio sets the initial ( -Xms -Xmx ) ) and maximum ( Java heap sizes to the same values. ry with a maximum of 32,768 MB. PacBio recommends The default for SMRT View is 20% of the total memo using the defaults. Enter the initial memory SMRT View Server (in MB) [20096]: Enter the maximum memory SMRT View Server (in MB) [20096]: Using SMRT View port (computed default, accepted): 9094 Using SMRT View initial memory (computed default, accepted): 20096 Using SMRT View maximum memory (computed default, accepted): 20096 Part 5 of 10: Database Setup e which will need access to a netwo The SMRT Link server uses a databas rk port and a directory to store database data files. • The port will only be used to access the database from the install host. • The database data directory should be located on a local (not shared) disk partition. • The default location will be in the SMRT Link Local File System Root Directory, specified above. Enter the SMRT Link Database port [9095]: Enter the full path to the 'dbdatadir' directory [/path/to/smrtroot/userdata/db_datadir.default]: Directory '/path/to/smrtroot/userdata/db_datadir.default' does not exist. Create it? [Y/n]: Creating directory '/path/to/smrtroot/userdata/db_datadir.default'... Using SMRT Link Database port (computed default, accepted): 9095 Using Database data dir (computed default in a previous install, accepted): /path/to/smrtroot/userdata/ db_datadir.default Part 6 of 10: User-Sp ecific Directories Setup The following directories should be configured to point to the actual locations: jobs_root tmp_dir jobs_root : This directory stores output from SMRT Analysis and needs to be large: >15 TB. Enter the full path to the 'jobs_root' directory [/path/to/smrtroot/userdata/jobs_root.default]: Directory '/path/to/smrtroot/userdata/jobs_root.default' does not exist. Create it? [Y/n]: Creating directory '/path/to/smrtroot/userdata/jobs_root.default'... tmp_dir : This directory is used for fast I/O operations, and should be a local directory ( not NFS-mounted) and needs to be large for large genome assembly jobs (>100 GB minimum, 1 TB recommended). This directory will be automatically created, as needed, on compute cluster nodes. The directory must exist on each cluster node and be writable to t he SMRT Link user. If missing, SMRT Link will attempt to create this destination, if permissions permit. Enter the full path to the 'tmp_dir' directory [/tmp/smrtlink]: /tmp/smrtlink: Page 12

13 Using jobs_root (computed default, accepted): /path/to/smrtroot/userdata/jobs_root.default Using tmp_dir (default, accepted): /tmp/smrtlink te Service Setup Part 7 of 10: Remo SMRT Link provides the following services, which require connection to PacBio servers: ) • SMRT Link Event Service (outbound https port 8083 • SMRT Link Update Service (outbound http port 8084 ) The SMRT Link Event Service provides the ability to send to PacBio: 1. Installation troubleshooting logs 2. Analysis failure logs, and 3. SMRT Link usage information, not including sample names or sequence data. The provides automatic notification and inst allation of chemistry bundle files com- SMRT Link Update Service patible with new PacBio consumables. Connection to PacBio servers be enabled in order to use the Event and Update Services. However, the must Services will not be avail able and user-specific data will not be transferred without additional opt-in via the SMRT Link GUI or command line. Enable connection to SMRT Link Event Server? [Y/n]: Enable connection to SMRT Link Update Server? [Y/n]: Test connectivity to the remote URLs? [Y/n]: Checking remote service URLs... Checking SMRT Link Event Service URL... ok Checking SMRT Link Update Service URL... ok All enabled remote service URLs are available. Using 'SMRT Link Event Service' Enable (configured interactively): true Using 'SMRT Link Update Service' Enable (configured interactively): true alysis Job Email Notification Part 8 of 10: SMRT Link An SMRT Link can be configured to s end email notifications of completed ana lysis jobs to the user who launched the analysis (for both successful and failed jobs). • SMRT Link only supports connections to SMTP Relays without encryption. Servers using basic authentication, SSL/TLS, or STARTTLS are not supported. • Email notification is disabled if t he outgoing mail serv er host is empty. Enter the SMRT Link notification outgoing mail server host []: mail.somedomain.com Enter the SMRT Link notification mail port [25]: Enter the SMRT Link notification mail user []: No mail user specified. Enabling SMRT Link mail notification, but disabling mail server authentication. Send a test message? [N/y]: y Enter target email address: []: [email protected] Page 13

14 Sending test email address to '[email protected]'... Email to '[email protected]' sent successfully. Please check email for test message. Keep current email notification settings? [Y/n]: Part 9 of 10: Distributed Computing Setup . You may attempt to manually configure , LSF, PacBio has validated SLURM PBS Sun Grid Engine (SGE), and not guaranteed to work. for alternate job management systems, but these are jobs to a distributed compute environment. If no A Job Management System may be used to dispatch Job Management System is specified, the system will run in Non-Distributed Mode, and compute jobs will be run all stems will be detected from the PATH environment locally on the install host. Available Job Management Sy variable, but may also be selected manually. For more information on customizing all of the Job Management Systems, edit the environment variables $SMRT_ROOT/userdata/user_jmsenv/user.jmsenv.ish. located in the file Note that changes to this file will apply to every job submitted to the cluster. Auto-detected the following Job Management Systems: SGE (From PATH: /usr/bin) Pick an option: 1) SGE 2) Other JMS 3) None (Non-Distributed Mode) Choice [1]: Using jmstype (selected interactively): SGE SGE Configuration If using Sun Grid Engine, or other *GE job schedulers, sele ct Option 1 (SGE). The install script will attempt to SGE_ROOT discover SGE_CELL , and SGE_BINDIR environment variables. If these are not found, type them in , manually when prompted. The queue name and parallel envir onment must also be chosen from a discovered list. If more environmental variables need to be defined, enter them in the file $SMRT_ROOT/userdata/user_jmsenv/user.jmsenv.ish. Detecting SGE setup (locations of binaries, SGE_ROOT, SGE_CELL)... Detected the following settings: SGE_ROOT=/usr/share/gridengine SGE_CELL=default SGE_BINDIR=/usr/bin Where detected: SGE_ROOT (from 'SGE_ROOT environment variable') SGE_CELL (from 'SGE_CELL environment variable') SGE_BINDIR (from 'PATH environment variable, default') Are these correct [Y/n]: Using the following settings: SGE_ROOT=/usr/share/gridengine SGE_CELL=default SGE_BINDIR=/usr/bin Select the queue to use for SMRT Analysis jobs: Pick an option: 1) default Page 14

15 2) fast 3) bigmem Choice [1]: 3 Select the parallel environment to use for SMRT Analysis jobs: Pick an option: 1) smp 2) mpi Choice [1]: Additional arguments to the SGE job submission command may be added in SGE_STARTARGS. The default job submission command is: qsub -S /bin/bash -sync y -V -q ${QUEUE} -N ${JOB_NAME} \ -o ${STDOUT_FILE} -e ${STDERR_FILE} \ -pe ${PE} ${NPROC} ${CMD} Specify extra 'qsub' args, SGE_STARTARGS []: Using SGE_ROOT (SGE_ROOT environment variable): /usr/share/gridengine Using SGE_CELL (SGE_CELL environment variable): default Using SGE_BINDIR (PATH environment variable, default): /usr/bin Using SGE_QUEUE (selected interactively): bigmem Using SGE_PE (selected interactively): smp Using SGE_STARTARGS (default, accepted): Using use_settings_file flag (computed): false Checking setting for the SGE SMRTAnalysis queue (bigmem, smp)... Checking that the queue is valid... Checking that the pe is valid... Checking that the pe is in the queue pe_list... Checking the pe allocation_rule... Checking the queue hostlist... PBS Configuration PBS_BINDIR If using the PBS Job Scheduler, select Option 1 (PBS). The install script will attempt to discover and PBS_QUEUE environment variables. If these are found, type them in manually when prompted. If more not environmental variables need to be defined, enter them in the file $SMRT_ROOT/userdata/user_jmsenv/user.jmsenv.ish. Auto-detected the following Job Management Systems: PBS (From PATH: /opt/pbs/bin) Pick an option: 1) PBS 2) Other JMS 3) None (Non-Distributed Mode) Choice [1]: Using jmstype (selected interactively): PBS Detected the following settings: PBS_BINDIR=/opt/pbs/bin PBS_QUEUE= (Use PBS default queue, currently: 'defqueue') PBS_STARTARGS= Where detected: PBS_BINDIR (from 'PATH environment variable, default') PBS_QUEUE (from 'default') PBS_STARTARGS (from 'default') Page 15

16 Are these correct [Y/n]: n Specify PBS_BINDIR [/opt/pbs/bin]: Select PBS_QUEUE: Pick an option: 1) defqueue (PBS default queue) 2) batch 3) --NONE-- (Use PBS default queues, currently 'defqueue') Choice [3]: 2 Additional arguments to the PBS job submission command may be added in PBS_STARTARGS. The default job submission command is: qsw ${CMD} -S /bin/bash -V -q ${QUEUE} -N ${JOB_NAME} \ -o ${STDOUT_FILE} -e ${STDERR_FILE} -l nodes=1:ppn=${NPROC} -PBS Specify extra 'qsub' args, PBS_STARTARGS []: Use the existing start and stop commands (i.e. qsw, qdel)? [Y/n]: Using jmstype (selected interactively): PBS Using PBS_BINDIR (PATH environment variable, default, accepted): /opt/pbs/bin Using PBS_QUEUE (configured interactively): batch Using PBS_STARTARGS (default, accepted): Using PBS start cmd (default): qsw Using PBS stop cmd (default): qdel LSF Configuration If using the LSF Job Scheduler, select Option 1 (LSF). The install script will attempt to discover LSF_BINDIR , LSF_SERVERDIR , LSF_LIBDIR , and LSF_ENVDIR environment variables. If these are not found, type them in manually when prompted. If more environmental variables need to be defined, enter them in the file $SMRT_ROOT/userdata/user_jmsenv/user.jmsenv.ish. Auto-detected the following Job Management Systems: LSF (From PATH: /opt/lsf/bin) Pick an option: 1) LSF 2) Other JMS 3) None (Non-Distributed Mode) Choice [1]: Using jmstype (selected interactively): LSF Detected the following settings: LSF_BINDIR=/opt/lsf/bin LSF_QUEUE= (Use default queue, currently: 'defqueue') LSF_STARTARGS= Where detected: LSF_BINDIR (from 'PATH environment variable, default') LSF_QUEUE (from 'default') LSF_STARTARGS (from 'default') Are these correct [Y/n]: n Specify LSF_BINDIR [/opt/lsf/bin]: Page 16

17 Select LSF_QUEUE: Pick an option: 1) defqueue (LSF default queue) 2) normal 3) interactive 4) longrun 5) --NONE-- (Use LSF default queues, currently 'defqueue') Choice [5]: 2 Additional arguments to the LSF job submission command may be added in LSF_STARTARGS. The default job submission command is: bsub -K -J ${JOB_NAME} -o ${STDOUT_FILE} -e ${STDERR_FILE} \ -n ${NPROC} -q ${QUEUE} -R "span[hosts=1]" ${CMD} Specify extra 'bsub' args, LSF_STARTARGS []: Using jmstype (selected interactively): LSF Using LSF_BINDIR (PATH environment variable, default, accepted): /opt/lsf/bin Using LSF_QUEUE (configured interactively): normal Using LSF_STARTARGS (default, accepted): SLURM Configuration If using the SLURM Job Scheduler, select Option 1 (SLURM). The install script does not attempt to discover must assign the following environm ent variables in the file environment variables. To configure SLURM, you $SMRT_ROOT/userdata/user_jmsenv/user.jmsenv.ish: • BINDIR should be set to the directory that contains the srun and the salloc SLURM binaries. PARTITION the "queue" in other JMS systems. is basically what is known as • PRESTARTARGS salloc . • are for any additional arguments to STARTARGS • srun . are for any additional arguments to Auto-detected the following Job Management Systems: Slurm (From PATH: /opt/slurm/bin) Pick an option: 1) Slurm 2) Other JMS 3) None (Non-Distributed Mode) Choice [1]: Using jmstype (selected interactively): Slurm Detected the following settings: SLURM_BINDIR=/opt/slurm/bin SLURM_PARTITION= (Use Slurm default partition, currently: 'defqueue') SLURM_PRESTARTARGS= SLURM_STARTARGS= Where detected: SLURM_BINDIR (from 'PATH environment variable, default') SLURM_PARTITION (from 'default') SLURM_PRESTARTARGS (from 'default') SLURM_STARTARGS (from 'default') Are these correct [Y/n]: n Page 17

18 Specify SLURM_BINDIR [/opt/slurm/bin]: Select SLURM_PARTITION: Pick an option: 1) defqueue (Slurm default partition) 2) normal 3) fast 4) long 5) --NONE-- (Use Slurm default partition, currently 'defqueue') Choice [5]: 2 Additional arguments to the Slurm job submission command may be added in SLURM_PRESTARTARGS (for salloc) and SLURM_STARTARGS (for srun. The default job submission command is: salloc --jobname"${JOB_NAME} --nodes=1 --cpus-per-task=${NPROC} \ --partition=${PARTITION} \ srun --cpus-per-task=${NPROC} \ --ntasks 1 -o ${STDOUT_FILE} -e ${STDERR_FILE} \ --partition=${PARTITION} ${CMD} Specify extra 'salloc' args, SLURM_PRESTARTARGS []: Specify extra 'srun' args, SLURM_STARTARGS []: Using SLURM_BINDIR (PATH environment variable, default, accepted): /opt/slurm/bin Using SLURM_PARTITION (configured interactively): normal Using SLURM_PRESTARTARGS (default, accepted): Using SLURM_STARTARGS (default, accepted): For Other JMS Configurations: When no JMS is automatically detected, select Option 2 (Other JMS). Auto-detected the following Job Management Systems: NONE (No JMS Detected) Pick an option: 1) None (Non-Distributed Mode) 2) Other JMS Choice [1]: 2 Pick an option: 1) SGE 2) OGS 3) UGE 4) PBS 5) TORQUE 6) PBSPro 7) LSF 8) OpenLava 9) Slurm 10) OtherJMS (Other/Unrecognized Third Party JMS) 11) CustomJMS (Custom JMS) 12) None (Non-Distributed Mode) Choice [12]: 10 Using jmstype (selected interactively): OtherJMS__* Page 18

19 Detected the following settings: OTHERJMS_NAME= OTHERJMS_BINDIR= OTHERJMS_QUEUE= OTHERJMS_STARTARGS= where detected: OTHERJMS_NAME (from 'default') OTHERJMS_BINDIR (from 'default') OTHERJMS_QUEUE (from 'default') OTHERJMS_STARTARGS (from 'default') Could not determine OTHERJMS_NAME setting, please specify below. Specify OTHERJMS_NAME []: prun Specify OTHERJMS_BINDIR []: /opt/prun/bin Select OTHERJMS_QUEUE: []: normal Specify extra args, OTHERJMS_STARTARGS []: Using OTHERJMS_NAME (configured interactively): prun Using OTHERJMS_BINDIR (configured interactively): /opt/prun/bin Using OTHERJMS_QUEUE (configured interactively): normal Using OTHERJMS_STARTARGS (default, accepted): Part 10 of 10: Dist ributed Computing Configuration Setup Configure the following options for distributed computing: NWORKERS, NPROC, TOTAL_NPROC, CHUNKING, MAXCHUNKS NWORKERS : Specifies the maximum number of simultaneous SMRT Link jobs that can be run by the SMRT ysis jobs as well export of Data Sets and import of FASTA references. Link server, including anal Page 19

20 • Data Set imports are processed separately and are not subject to this limit. These are independent jobs that then submit multiple pipeline tasks to the cluster. • NWORKERS should be set to no more than the number of processors available on the SMRT Link server machine. The default is the number of processors on the head node, and will not exceed 32. controls the number of analysis jobs that can be run on the SMRT Link server. For exam- NWORKERS maximum to two, you will only see two "RUNNING" j obs in the SMRT Anal ysis section - creating ple, if you set NWORKERS put them in the "CREATED" or “SUBMITTED” state. The default value for more jobs in SMRT Link would only NWORKERS rarely needs to be changed. Enter the max number of workers 'NWORKERS' [24]: NPROC maximum number of slots available per task on each compute node. The suggested : Specifies the value is determined by the processor count of the SMRT Link system (assuming 1 core per slot), but should be no greater mpute nodes. This controls the largest number that set than the lowest slot count on the available co will be requested to the cluster resource for the distribu ted tasks from SMRT Link. To ensure that more distrib- uted tasks from SMRT Link can be run, consider using a number that can fit the smaller nodes in the cluster facility. Example 1: Fitting more tasks in a heterogeneous cluster If you have 3 large nodes with 96 cores each, and 3 small nodes with 16 core each, set the NPROC to 15 or 16 to fit more tasks into the cluster. Example 2: Adjusting for memory constraints If you have a node with 50 cores but only with 200 GB memory, NPROC should be set to less than 25 so that SMRT Link tasks can access enough memory (one slot is allocated 8 GB of memory). Enter the number of processors per task 'NPROC [23]: TOTAL_NPROC maximum number of total processors/slots that may be consumed by pbsmrt - : Specifies the . This setting is more relevant if you running on a single node and pipe TOTAL_NPROC to not using a JMS. Use reduce the maximum number of processors. TOTAL_NPROC has no effect if set to higher than the limit of slots, as determined by the product of NPROC * MAXCHUNKS . For example, if your single-node system has 64 CPUs, then set to 1 and TOTAL_NPROC to something less than 64. NWORKERS Enter the total number of processors 'TOTAL_NPROC' [1000]: CHUNKING : Specifies whether large files shoul d be broken up into smaller chunks. Enable chunking 'CHUNKING' [Y/n]: MAXCHUNKS : Specifies the maximum number of chunks when breaking up large files. Enter the max number of chunks 'MAXCHUNKS' [24]: Using NWORKERS (computed default, accepted): 24 Using PROC (computed default, accepted): 23 Using TOTAL_NPROC (default, accepted): 1000 Using CHUNKING (configured interactively): true Using MAXCHUNKS (default, accepted): 24 End of Log Output Saving config... Applying settings... Page 20

21 Applying jms settings... Creating user.jmsenv.ish file... Generating jmsenv.ish file... Generating jms template files... Applying dirlinks settings... Applying smrtslag preset.xml settings... Applying smrtslag config.json settings... Installing smrtlink-system-config.json... Validating smrtlink-system-config.json... Applying database settings... Running smrtlink-analysisservices-gui apply-config... Running smrtlink-analysisservices-gui upgrade... Successfully Completed apply-config Successfully completed running smrtflow.tools.apply_config 0.3.0 (smrtflow 0.10.0+19302.ffa7e32) in 1 sec. Applying smrtview settings... Running smrtview apply-config... SMRT Link Install successful. User-specific configurations can be injected into JMS commands in two ways: qsub arguments: 1. During the installation or reconfiguration, specify the following extra . SGE_STARTARGS []: "-l mem_free=2G, h_rt=120:0:0" guration, the following steps are required to apply the changes: Note that if performing a reconfi A) $SMRT_ROOT/smrtlink/admin/bin/services-stop $SMRT_ROOT/smrtlink/admin/bin/smrt_reconfig . This will regenerate the configuration files B) performing a complete reinstall of the software. without C) $SMRT_ROOT/smrtlink/admin/bin/services-start New configuration settings will be automatically . applied following a restart of SMRT Link Services. 2. By adding the configurations to $SMRT_ROOT/smrtlink/userdata/user_jmsenv/user.jmsenv.ish . , define : To specify resource request list for and h_rt to SGE Example mem_free qsuboptions in the qsub variable SGE_STARTARGS . To do so, add the following line to $SMRT_ROOT/smrtlink/userdata/user_jmsenv/user.jmsenv.ish : SGE_STARTARGS="-l mem_free=2G, h_rt=120:0:0" Note: Restarting SMRT Link Services is not needed. Changing the pbicsuser account password in SMRT Link 1. Log in to the WSO2 Carbon Administration page at https://:9443/carbon where hostname is the SMRT Link host. ). 2. In the left-hand menu, click List (under Users and Roles Page 21

22 3. Search for the user pbicsuser Change Password . , then click Change 4. Enter the new password twice and click . 5. The screen should display a confirmation dialog indicating that the action was successful. 6. To be absolutely certain that everything is working on the SMRT Link side, we recommend that you log in as after pbicsuser Sample Setup changing the password. Most functionality should be enabled except for (which is not used by the instrument itself). You can also run the following command to test authentication: $SMRT_ROOT/smrtcmds/bin/pbservice status --host servername --user pbicsuser --ask-pass and enter the password when requested. Note : The pbicsuser account password in the Instrument Control Software (ICS) must also be changed to match the new password. Please contact PacBio Technical Support for details. Changing Your Usage Tracking Settings Use the command-line accept-user-agreement tool to view and/or change the usage tracking you chose during installation or upgrade. 1. View the current User Agreement settings: $ curl -XGET http://localhost:8081/smrt-link/eula | python -m json.tool Sample response, with installation metrics and job data sent to PacBio: "acceptedAt": "2018-07-11T13:05:19.147Z", "enableInstallMetrics": true, "enableJobMetrics": true, "osVersion": "Linux version 3.13.0-33-generic ([email protected]) (gcc version 4.8.2 (Ubuntu Page 22

23 4.8.2-19ubuntu1) ) #58-Ubuntu SMP Tue Jul 29 16:45:05 UTC 2014\n", "smrtlinkVersion": "6.0.0.SNAPSHOT40824", "user": "admin" JobMetrics sending SMRT Link job data to PacBio, both enable InstallMetrics and enable enable 2. To true . To do so, enter the following command: must be set to $ accept-user-agreement --update true --install-metrics true --job-metrics false --host localhost --port 8081 --log2stdout disable sending SMRT Link job data to PacBio, set --job-metrics to false by entering the following 3. To command: $ accept-user-agreement --update true --install-metrics true --job-metrics false --host local- host --port 8081 --log2stdout Note for more information about SMRT Link installation and Job metrics configuration. : Use --help LDAP Integration LDAP for user login authentication. Without LDAP integration with SMRT SMRT Link supports integration with one Link, only admin/admin ) is enabled. user (with the login If you are interested in configuring SMRT Link integration with your organization’s LDAP, PacBio recommends that you consult your LDAP administrator to help determine the correct LDAP settings. Note : Since SMRT Link v4.0.0, exis ting LDAP configurations are automatically migrated during upgrade. Changing the Password for the Admin Account Note : Do not change the admin password for the admin/admin account by only using the WSO2 API Manager. Please follow these steps carefully, otherwise you will not admin account. be able to access the built-in WSO2 API Manager admin . 1. Open and login as Users and Roles , Click List > Users > Change Password for admin user . 2. Under 3. Sign-out , and shut down SMRT Link using $SMRT_ROOT/admin/bin/services-stop Click 4. Change the password in the following files: Line 26 in $SMRT_ROOT/current/bundles/smrtlink-analysisservices-gui/current/private/pac - bio/smrtlink-analysisservices-gui/wso2am-2.0.0/repository/conf/user-mgt.xml Lines 19 and 21 in $SMRT_ROOT/current/bundles/smrtlink-analysisservices-gui/current/private/ pacbio/smrtlink-analysisservices-gui/wso2am-2.0.0/repository/conf/jndi.properties 5. Enter $SMRT_ROOT/admin/bin/set-wso2-creds --user 'admin' --password 'newpassword' 6. Start SMRT Link services again using $SMRT_ROOT/admin/bin/services-start Configuring LDAP • LDAP is configured after SMRT Link v6.0.0 is installed, using the WSO2 API Manager software, as shown below. first configure LDAP before you can enable a network user to be a SMRT Link user, and specify • You must their role. https://:9443/carbon/ where < hostname > is the host 1. Enter the following in your browser: where SMRT Link is installed. Page 23

24 2. Login using admin/admin . User Stores > Add 3. Click . 4. Edit the fields as necessary for your site. required . ( Note The following fields are : Values provided in the example above are listed below for clarity. Actual values should be provided by your LDAP administrator): • User Store Manager Class: org.wso2.carbon.user.core.ldap.ReadOnlyLDAPUserStoreManager • Domain Name: university.edu • Connection URL: ldap://ldap.university:389 • Connection Name: CN=ldapadmin,CN=users,DC=university,DC=edu • Connection Password: • User Search Base: CN=users,DC=university,DC=edu • Username Attribute: uid • User Search Filter: (&(objectClass=person)(uid=?)) • User List Filter: (objectClass=person) • Display name attribute: uid For more information on LDAP, consult the following web pages: https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol https://en.wikipedia.org/wiki/LDAP_Data_Interchange_Format https://msdn.microsoft.com/en-us/library/ms677605%28v=vs.85%29.aspx Problems with the LDAP server may be debugged by looking at the log file located here: Page 24

25 $SMRTLINK/current/bundles/smrtlink-analysisservices-gui/current/private/pacbio/ smrtlink-analysisservices-gui/wso2am-2.0.0/repository/logs/wso2-apigw-errors.log ® SMRT Link User Roles , Instrument , and Bioinformatician . (A fourth role, Admin , SMRT Link supports three user roles: Lab Tech displays in the User Management page. The Sequel Instru ment Control Software uses this role to communicate with SMRT Link. Do not assign any SMRT Link users to this role.) Roles define which SMRT Link modules a user can access. The following table lists the priv ileges associated with the three user roles: Lab Tech Bioinformatician Tasks/Privileges Admin N N Add/Delete SMRT Link Users Y N Assign roles to SMRT Link users N Y N Update SMRT Link software N Y Access Sample Setup Module Y N Y Access Run Design Module N Y Y Y Y Y Access Run QC Module Access Data Management Module Y Y Y Y Y Y Access SMRT Analysis Module PacBio recommends the following role assignments: at least one user per site the Admin role. That individual is responsible for enabling and disabling •Assign SMRT Link users, as well as specifying their roles. The Admin can also access all SMRT Link modules, as well as every file in the system. (SMRT Link supports multiple users with the Admin role per site.) Lab Tech • Assign users who work in the lab preparing samples and performing runs the can role. Lab Tech also access all SMRT Link modules. role. can • Assign users who work access only Bioinformatician only Bioinformatician on data analysis the the Run QC, Data Management and SMRT Analysis modules; this is the lowest access level. Adding SMRT Link Users and Assigning User Roles before first • You must you can manage users and assign SMRT Link roles to users. configure LDAP be able to login not a user, that user will assign a SMRT Link role to not • After LDAP is configured, if you do to SMRT Link. SMRT Link > 1. is the host where SMRT Link is hostname < , where http://:9090 : Enter Access installed. Configure User Management . from the SMRT Link menu and click 2. Choose 3. There are 2 ways to find users: To display all SMRT Link users : Click Display all Enabled Users . • To find a specific user : Enter a user name, or partial name and click Search By Name • . , the user has access to SMRT Link; means the 4. Click the desired user. If the Status is Disabled Enabled user access SMRT Link. cannot add a SMRT Link user: Click the Enabled •To button, then assign a role. (See Step 5.) •To delete a SMRT Link user: Click the Disabled button. blank field and select one of the three roles. (A role means that this user cannot access Role 5. Click the SMRT Link.) Page 25

26 6. Click Save . The user now has access to SMRT Link, based on the role just assigned. ® Link and SSL Certificate Procedures SMRT SMRT Link v6.0.0 uses SSL (Secure Sockets Layer) to enable access via HTTPS (HTTP over SSL), so that your SMRT Link logins and data are encrypted during tr ansport to and from SMRT Link. SMRT Link includes an Identity Server, which can be configured to integrate with your LDAP/AD servers and enable user authentication using your organizations’ user name and password. To ensure a secure connection between the SMRT Link completing SMRT Link installation. server and your browser, the SSL Certificate can be installed after It is important to note that PacBio will not provide a Signed SSL Certificate. However, once your site has obtained a Signed SSL Certificate, PacBio’s tools can be used to install it and configure SMRT Link to use it. Note : PacBio recommends that you consult your IT administrator about obtaining an SSL Certificate.) You will ( need a certificate issued by a Certificate Authority (CA, sometimes referred to as a “certification authority”). PacBio has tested SMRT Link with certificates from the following certificate vendors: VeriSign, Thawte and DigiCert. If your site does not provide an SSL Certificate, SMRT Link v6.0.0 will use a PacBio self-signed SSL Certificate. each user will need to accept the browser warnings related to access If you use the self-signed SSL Certificate, your IT administrator configure desktops to always trust the pro- in insecure environment. You can also have stalled within your organization’s secure network, behind vided self-signed Certificate. Note that SMRT Link is in your organization’s firewall. See “Using SMRT Link with a PacBio Self-Signed SSL Certificate” on page 30 for details on how to handle the security warnings when accessing SMRT Link. Use the following procedures if your site provides an SSL Certificate. These procedures are not applicable only if you are using PacBio’s Self-Signed SSL Certificate. Note already setup an SSL Certificate in SMRT Link v4.0.0, those settings will be carried over : If you have automatically when upgrading to SMRT Link v6.0.0. Prerequisites Please consult your system administrator if you need the following programs installed: 1. : This common package is available on all of the ma jor distributions through their package installers. openssl 2. keytool : Part of the standard Java Runtime. Note: If you already have a complete .jks file, including the signed certificate, see “Installing an Existing Certif- file needs to be generated using the appropriate password/alias. icate” on page 29 . Note that the .jks Page 26

27 Configuring WSO2 in SMRT Link to Use a Signed SSL Certificate SMRT Link requires updates to the Deploying a signed SSL certificate to av oid the browser warning when using authentication and manages user rights and roles. This third-party WSO2 API Manager software, which handles process requires several steps, most of which need to be run on the command line: 1. Purchase the signed certificate from the certificate authority. 2. Generate a private/public key pair and a Certificate Signing Request (CSR). truststore file that includes the new key. 3. Create a new ificate key. (This part is automated using the included 4. Update the WSO2 configuration to use the signed cert install_ssl_cert.sh .) script 5. If LDAP has already been configured, reenter the password in the WSO2 Administrative interface. Key file and Certificate Sign ing Request (C SR) Generation For clarity, this document uses variables for some of the subsequent steps: SMRT_ROOT="/path/to/smrtlink" FQDN="hostname.domain.com" KEYPW="password" KEYNAME="hostname_domain_com" KEYSTORE="${KEYNAME}.jks" TRUSTSTORE="client-trustore.jks" Edit and KEYPW as appropriate for your site. FQDN Generate a certificate-signing request ( .csr ) and a keystore ( .jks ) file. Step 1: internal SMRT Link servers. We also provide a tool to At PacBio, we used DigiCert to obtain certificates for our generate the appropriate command for creating the key and keystore files. If your organization’s chosen certifi- cate authority does not provide this information, below is an example of the commands necessary: $ keytool -genkey -alias server -keyalg RSA -keysize 2048 -keystore hostname_domain_com.jks -dname "CN=hostname.domain.com, O=Company Name, L=City, ST=CA, C=US" $ keytool -certreq -alias server -file hostname_domain_com.csr -keystore hostname_domain_com.jks Enter keystore password: Re-Enter new password: Output hostname_domain_com.csr, hostnamet_domain_com.jks (private key) Notes on Passwords and Aliases Many of the following steps require entry of a new password. This password: • Must be the same as the one entered at the command-line for WSO2. • Should be unique for this purpose and not be reused anywhere else, although it may be shared across multiple instances that use the same SSL certificate. smrtlink • Should be non-obvious ; note that it will be stored in plain text in multiple configuration files. The alias needs to be explicitly set to server everywhere for the ce rtificate configuration. Now that you have the certificate-signing request, you can use it to request a new certificate from DigiCert or any other certificate authority. If using DigiCert, the SSLPlus product is suitable for a single SMRT Link instance, but wild card certificates for an entire domain ar e available at a higher price. This process is very fast. . Step 2 : Download the new certificate in .p7b format from the DigiCert website hostname_domain_com.p7b Page 27

28 Step 3 : Combine the certificate and the keystore files: $ keytool -import -trustcacerts -alias server -file ${KEYNAME}.p7b -keystore ${KEYNAME}.jks Enter keystore password: Certificate reply was installed in keystore .pem Step 4 format: : Generate an intermediate file in $ keytool -export -alias server -keystore ${KEYNAME}.jks -file ${KEYNAME}.pem Enter keystore password: Certificate stored in file client-truststore.jks Step 5 .pem file: : Generate the WSO2 truststore file using the $ keytool -import -alias server -file ${KEYNAME}.pem -keystore client-truststore.jks -storepass $KEYPW Trust this certificate? [no]: y Certificate was added to keystore Step 6 ${SMRT_ROOT}/admin/bin/services-stop . : Stop the services by entering : Install the new files and update the configuration files: Step 7 .jks ${SMRT_ROOT}/admin/bin/install_ssl_cert.sh ${FQDN} ${KEYSTORE} ${TRUSTSTORE} ${KEYPW} RT Link, removing the browser warnings that occur when This script will install a signed SSL certificate to SM using the default certificate. To run this script, you will need two files in Java Key Store ( ) format: .jks • One containing the SSL keys and certificate. client-truststore.jks required by the authentication manager. • A separate Usage : install_ssl_cert.sh $FQDN $KEYSTORE $TRUSTSTORE $KEYPW where: • $FQDN is the fully-qualified domain name appropriate to the signed SSL Certificate, such as . smrtlink.university.edu $KEYSTORE is the path to the keystore file generated from the SSL Certificate ( .jks extension); this will be • copied to the SMRT Link installation. is the path to client-truststore.jks . $TRUSTSTORE • • $KEYPW is the password used for generating keys. The FQDN must match the dnsname specified in the installer The shorthand (such as " smrtlinkhost ") will not work because the certificate is for a domain name, an unqualified hostname. When running the SMRT Link not installer, do this by passing the arguments --dnsname $FQDN . Also note that if you are using LDAP authentication, you may need to reenter the password for the LDAP connection in the WSO2 administrative interface on ce SMRT Link has been started again, for example: https://smrtlink.pacb.com:9443/carbon . This is because the password is stored encrypted with the SSL certificate key, which has now changed. Step 8 : Start SMRT Link services by entering $SMRT_ROOT/admin/bin/services-start . Final Check: Step 9: Page 28

29 Go to http://hostname:9090 (if LDAP is not enabled). Note that SSL is not used and login as admin/admin on the UI port (i.e. 9090) because this only serves static content; the actual login credentials are sent to port 8243 which only uses SSL. You will be redirected to , and should see a padlock sign https://hostname.domain.com:8243/sl/#/welcome in front of the URL which indicates that the site is secure. Viewing a Java Keystore File fy if the same password The keystore files for SSL certificates are binary files. Use the following command to veri d install process. If the same password was not used in the certif- was used in the SSL certificate generation an icate installation process, this command will give an erro r. To list the contents of a Java keystore file, use the command, as shown below: keytool -list Usage keytool -list -v -keystore keystore.jks : Example : keytool -list -v -keystore smrtlink-test_nanofluidics_com.jks Enter keystore password: Keystore type: JKS Keystore provider: SUN Your keystore contains 1 entry Alias name: server Creation date: Feb 13, 2017 Entry type: PrivateKeyEntry Certificate chain length: 3 Certificate[1]: Owner: CN=smrtlink-release-test.nanofluidics.com, O="Pacific Biosciences of California, Inc.", L=Menlo Park, ST=CA, C=US Issuer: CN=DigiCert SHA2 Secure Server CA, O=DigiCert Inc, C=US Errors/logs related to certificate installation can be found here: $SMRT_ROOT/current/bundles/smrtlink-analysisservices-gui/current/private/pacbio/smrtlink- analysisservices-gui/ Installing an Existing Certificate already have a complete .jks file (suitable for Apache Tomcat, fo If you r example), including the signed certifi- cate, you just need to change the alias of the keystore/certificate to server using the keytool command ( -keyclone or -changealias subcommands). Set the password to whatever you will supply to the instal l script in SMRT Link. Then, follow the instructions in "Adding the public key to client-truststore.jks" in https://docs.wso2.com/display/IS500/Creating+New+Key- stores again with the same changes. If you already have the SSL key in a .jks file and have obtained a certificate for this key in PKCS #7 Certificate format ( .p7b ), run this command to combine them: $ keytool -import -trustcacerts -alias server -file star.university.edu.p7b -keystore star.university.edu.jks Then follow the instructions above to generate the client-truststore.jks file, and run the install script. Recovering from the SSL Certificate Installation It may sometime be necessary to uninstall the user-provided SSL certificate and restore the default certificate. : The following steps will revert changes made by $SMRT_ROOT/admin/bin/install_ssl_cert.sh Page 29

30 1. Stop SMRT Link services: $SMRT_ROOT/admin/bin/services-stop Check that all SMRT Link proc ps -ef | grep smrtlink . 2. esses have terminated by running Remaining . processes should be terminated with kill or kill -9 3. Restore backup settings: cd ${SMRT_ROOT}/current/bundles/smrtlink-analysisservices-gui/current/private/pacbio/smrtlink- analysisservices-gui/wso2am-2.0.0/repository mv conf conf.new mv conf.orig conf mv resources/security/client-truststore.jks.orig resources/security/client-truststore.jks 4. Start SMRT Link services: ${SMRT_ROOT}/admin/bin/services-start Using SMRT Link with a PacBio Self-Signed SSL Certificate -signed SSL Certificate. If your site does not have a Signed SSL SMRT Link v6.0.0 ships with a PacBio self and you use the self-signed SSL Certificate, Certificate each user will need to accept the browser warnings related to access in insecure environment. You can also have your IT administrator configure desktops to always trust the provided self-signed Certificate. Note that SMRT Link is installed within your organization’s secure network, behind your organization’s firewall. Security messages display when users try to login to SMRT Link for the first time using the Chrome browser. These messages may also display other times when accessing SMRT Link. Each SMRT Link user in your organization should address these browser warnings following the procedure below. 1. The first time you start SMRT Link after installation, you see the following text. Click the Advanced link. 2. Click the Proceed... link. (You may need to scroll down.) box in the corner. 3. Close the window by clicking the Close Page 30

31 4. The Login me and Password. The next time you access SMRT dialog displays, where you enter the User Na directly . Link, the Login dialog displays ® Client Software: Installin View g 64-bit Java 8 to run SMRT SMRT View is a genome browser that visualizes sequencing data generated by the Sequel System. : To run SMRT View, 64-bit Java (Version 8 or later) must be installed on your local Windows or • Note Macintosh host. Installing 64-bit Java 8 on Windows 1. Use Control Panel > Programs and Features to check for and uninstall all existing versions of Java. 2. Go to http://www.java.com/en/download/manual.jsp. Windows Offline (64-bit) . This downloads a 3. Click file. ( Note : Other Java versions are 32-bit, and x64.exe will work with SMRT View.) not .exe 4. Double-click the file to start the Java installer, and follow the installer directions. 5. After the installation is finished, restart the browser. Installing 64-bit Java 8 on Mac OS Note : This requires Mac OS 10.7.3 or later. all 1. Use the Finder to search for existing versions of Java, then drag them to the Trash to uninstall. 2. Go to http://www.java.com/en/download/manual.jsp. 3. Click Mac OS X . This downloads a x64.dmg file. 4. Double-click the .dmg file to mount the installer volume. 5. Double-click the Java icon to start the Java installer, and follow the installer directions. 6. After the installation is finished, restart the browser. ® Importing Data into SMRT Link If you have a Sequel System installed and it is linked to the SMRT Link software during the instrument installation, your Seq uel System data will be automatically imported in SMRT Link. manually import the following types of file You can s directly, using the SMRT Link GUI: • - FASTA files containing a reference sequence. Reference sequence files .fa or .fasta ) containing a GMAP reference sequence GMAP Reference FASTA • - FASTA sequence files ( for use in starting Iso-Seq analyses. • - An XML file ( gmapreferenceset.xml ) that points to a GMAP reference GMAP ReferenceSet (XML) ® FASTA file and indices for use in starting Iso-Seq analyses. • Sequel sequence data - A file ( .subreads.xml ) containing information about Sequel sequence data, such as paths to the BAM files. RS II sequence data - A file ( .metadata.xml) containing information about PacBio RS II sequence data • from one cell. .xml or FASTA-format files containing barcodes. • Barcodes/Barcodes (FASTA) - Page 31

32 You can also import data in SMRT Link using the command-line utility, as shown below. pbservice Services are optional and default to localhost:9090 . You can change • The host and port for the Analysis and --port arguments. these settings using the --host Importing Commands Import individual SubreadSet XML files: BAM Data Sets Generated by the $> pbservice import-dataset --host $HOST --port $PORT /path/to/ Sequel System subreads.subreadset.xml Import a directory of SubreadSet XML files: $> pbservice import-dataset --host $HOST --port $PORT /path/to/tree/ containing/subreadssets.xml/ PacBio RS II Data Import a Dataset XML file (Subreads, reference sequences, or barcode files): created with SMRT $> pbservice import-dataset --host smrtlink-release --port 9091 /path/to/data - Analysis versions set.xml prior to v3.0.0 A FASTA Reference Creating a ReferenceSet XML file from a FASTA file: fasta-to-reference hg38.fasta /opt/smrtlink/references hg38 --organism Homo_sapiens > fasta2ref.log 2>&1 Sending Log Files to Technical Support to PacBio Technical Support multiple ways. The following two methods Troubleshooting information can be sent require a connection to the PacBio Event Server and Update Server. . About > Troubleshooting Information > Send • From the SMRT Link menu: • From a SMRT Link “Failed” analysis Results page: Click . Send Log Files following command to generate a .tgz file and email If there is no connection to the PacBio Event Server, run the the file to [email protected] to file a case: $SMRT_ROOT/admin/bin/tsreport-install --bundle For Research Use Only. Not for use in diagnostic procedures. © Co pyright 2016 - 2018, Pacific Biosciences of California, Inc. A ll rights ny errors reserved. Information in this document is subject to change wit hout notice. Pacific Biosciences assumes no responsibility for a ns may pertain to yo ur use of Pacific Bi osciences or omissions in this document. Certain noti ces, terms, conditions and/or use restrictio products and/or third party products. Please refer to the applicab le Pacific Biosciences Terms and Conditions of Sale and to th e applicable license terms at https: //www.pacb.com/legal-and-trademar ks/terms-and-conditions-of-sale/. SMRTbell, Iso-Seq and Sequel are trademarks of Pacific Bioscie nces. Pacific Biosciences, the Pacific Biosciences logo, PacBio, SMRT, BluePippin and SageELF are trademarks of Sage Science, Inc. NG S-go and NGSengine are trademarks of GenDx. FEMTO Pulse and Fragment Analyzer are trademarks of Advanced Analytical Technologies. All other trademarks are the sole property of their respe ctive owners. P/N 100-749-900 Version 17 (October 2018) Page 32

Related documents