SnapLogic® Sidekick Guide

22
SnapLogic ® Sidekick Guide Document Release: July 2012 SnapLogic, Inc. 71 East Third Avenue San Mateo, California 94401 U.S.A. www.snaplogic.com

Transcript of SnapLogic® Sidekick Guide

Page 1: SnapLogic® Sidekick Guide

SnapLogic® Sidekick Guide 

 

Document Release: July 2012

 

 

 

 

 

 

 

 

 

 

 

 

SnapLogic, Inc.71 East Third AvenueSan Mateo, California 94401U.S.A. www.snaplogic.com

Page 2: SnapLogic® Sidekick Guide

Copyright Information

© 2011-2012 SnapLogic, Inc. All Rights Reserved. Terms and conditions, pricing, and other infor-mation subject to change without notice. ”SnapLogic” and “SnapStore” are among the trade-marks of SnapLogic, Inc. All other product and company names and marks mentioned are the property of their respective owners and are mentioned for identification purposes only. “Snap-Logic” is registered in the U.S. and Trademark Office.

Page 3: SnapLogic® Sidekick Guide

Table of Contents

SnapLogic® Sidekick Guide 1

Table of Contents 3

Sidekick Overview 5

Supported Platforms for Sidekick 6

Performance 6

Sidekick Registration and Communication Architecture 9

Data Communication 9

Configuration 11

Configuring Sidekick 13

Enabling Sidekick in Designer 13

Explicit Proxy Setting 13

Default Ports 14

Automatically Starting and Stopping Sidekick and SnapLogic Server on Linux 15

Auto Startup on RedHat-like Distribution (Red Hat, Fedora Core, CentOS, Suse) 15

Auto Startup on Debian-like Distribution (Debian, Ubuntu) 16

Sidekick Use Case 17

Appendix: Python Resources 19

Python Components 19

Python Snaps 19

- 3 -

Page 4: SnapLogic® Sidekick Guide

SnapLogic® Sidekick Guide

- 4 -

Page 5: SnapLogic® Sidekick Guide

Sidekick OverviewThe SnapLogic Sidekick is a service installed locally that lets you access data both on site behind a firewall and in the cloud. Sidekick can be installed anywhere on your network that has access to the data that you want to use. The advantage of using Sidekick instead of an on-premises installation of the SnapLogic Server is a lighter install and footprint on the ground. Sidekick's lighter footprint means that all Pipelines and associated metadata are stored in the cloud instance of the SnapLogic Server.

Sidekick communicates securely with the SnapLogic Server in the cloud through the Secure Bridge, a bi-directional (or two-way) secure connection. 

The SnapLogicServer is used to create new certificate pairs needed for Sidekick com-munication. The Sidekick Proxy's key responsibilities are:

 l Establishing two communication links with the SnapLogic Server in the cloud: one for operational communication, and the other for data transfers.

 l Self monitoring to ensure that the Sidekick Proxy is up and running

 l Rollbacks and recovery to the last stable version

 l Enabling an on-premises Component Container

Sidekick is essentially a SnapLogic Java Component Container (Java CC). A SnapLogic Server running in the cloud stores the metadata and controls the Sidekick service. When a Pipeline needs to run, Sidekick will execute the Pipelines following commands from the SnapLogic Server; actual Java code executes within the Sidekick.

- 5 -

1

Page 6: SnapLogic® Sidekick Guide

SnapLogic® Sidekick Guide

Note: When Sidekick is enabled, only the Java CC is running (as Sidekick). The Python CC is inaccessible.

There is no difference whether the Java CC is running on the ground (as Sidekick) or in the cloud. Snap logs are stored with the Sidekick, but logs can be shown in the Designer. If com-munication between the SnapLogic Server and Sidekick is interrupted, the server will no longer be able to talk to the Sidekick, so Pipelines will not be executed. Scheduled Pipelines have an option to be executed if they miss their window, so those Pipelines can still be run.

Once Sidekick is enabled, it becomes the Component Container used by theSnapLogic Server for Pipeline execution. Any data movement is initiated inside Sidekick. The only realtime data that flows in or out of Sidekick are Pipelines that utilize an input/output feed.

Supported Platforms for SidekickSidekick is supported on the following platforms:

 l RedHat Enterprise Linux 5/CentOS 5

 l Ubuntu 10.10, 64-bit

 l The Sidekick configuration page (accessible to the SnapLogic Server through the Designer menu bar, Server > Configure Sidekick) is only fully functional and tested with Chrome.

Minimum Requirements l The Sidekick host should have a minimum of 1.5 GB RAM and 15 GB HDD.

Note: How much RAM and hard drive space you need will vary depending on your Pipelines and the amount of data you are working with. 

 l For installation, root access is required. After that, the user snapuser can run Sidekick without needing root.

 l Network connectivity is required.

 l Make sure that the hostname configured on the Sidekick machine as displayed by the command ‘hostname’ can be resolved to an IP address and it matches one of the net-work interfaces of the host. If this is not properly configured, Sidekick will not start up. If this issue happens, you can edit /etc/hosts and create an appropriate entry.

 l Sidekick must have direct access to any databases or SaaS applications in your Pipe-lines. For anything outside the network, direct access through a corporate firewall is required.

PerformanceThe performance of your SnapLogic configuration can vary depending on:

 l the number of instances of SnapLogic Server

 l the systems specifications of your host machine

- 6 -

Page 7: SnapLogic® Sidekick Guide

Sidekick Overview

 l the performance of and connection to databases or other applications

 l the number and type of Components in your Pipelines (the longer and more complex the Pipeline, the longer it will take to complete)

The following use cases provide some examples of performance on Pipelines with large amounts of data.

Use Case: MySQL/Oracle to Salesforce

Inputs Outputs25 million rows, each row around 300 bytes Create/Update 25 million contacts in Salesforce

Configuration

 l SnapLogic Server on a  4 core, 6 GB virtual system.

 l SnapLogic  and MySQL database in the cloud within the same virtual server aver-ages 25,347,945 rows in 2 hours.

 l SnapLogic in the cloud and Oracle database in a local data center  averages 25,053,691 rows in 2 hours.

Use Case: Hadoop to MySQL

Inputs OutputsHadoop: 

 l 48 million rows data, each row  around 300 bytes

 l Total size 13.4 GB

8 million rows in MySQL

Configuration

 l SnapLogic Server on a  4 core, 6 GB virtual system.

 l A single instance of SnapLogic processes 48 million rows in 11.43 minutes (or  756 million rows in 3 hours).

 l Two  instances process 96 million rows in 14.35 minutes (or 1.2 billion rows in 3 hours).

 

- 7 -

Page 8: SnapLogic® Sidekick Guide

- 8 -

SnapLogic® Sidekick Guide

Page 9: SnapLogic® Sidekick Guide

Sidekick Registration and Communication ArchitectureThe following diagram highlights the architecture of Sidekick communication.

Sidekick initiates all communications with the SnapLogic Server. Since it is assumed that Side-kick is not accessible outside the firewall it is behind, the Server never initiates a connection to Sidekick. Sidekick uses an Apache Tomcat web server for its requests and responses.

Data CommunicationStep Description 1 Session Start

 l Sidekick initiates a TCP connection to the SnapLogic Server (HTTP: default 8088*/HTTPS: default 8091*)  

- 9 -

2

Page 10: SnapLogic® Sidekick Guide

SnapLogic® Sidekick Guide

Step Description * Firewall must allow outbound TCP trans-mission to this port

2 Sidekick Registration

 l Sidekick authenticates with the SnapLogic Server using Sidekick user credentials 

 l Once authenticated, Sidekick is allowed to begin SSL connection to the secure Cloud Proxy (SSL: default 8443*) which is termed as the “Secure Bridge”  * Firewall must allow outbound TCP trans-mission to this port

3 Sidekick Secure Bridge  

 l Sidekick makes a secure SSL con-nection to Cloud Proxy (SSL: default 8443*) to create a “Secure Bridge” using self-signed cer-tificates that were downloaded from the server after installation 

 l All communications between Server and Sidekick use this “secure bridge” SSL connection  

* Firewall must allow outbound TCP trans-mission to this port

4 Data Transmission over “Secure Bridge”

 l Heartbeats and Pipeline control commands are sent from the Snap-Logic Server to Sidekick 

 l Pipeline execution status infor-mation is sent from Sidekick to Server 

 l Pipeline execution and data move-ment is isolated to Sidekick

These are web service request/re-sponses using REST/JSON protocol.

5 Session End

 l Heartbeats and Pipeline control commands will continue to be 

- 10 -

Page 11: SnapLogic® Sidekick Guide

Sidekick Registration and Communication Architecture

Step Description transmitted from the SnapLogic Server to Sidekick via the secure Cloud Proxy until Sidekick is unreg-istered or disabled

     

ConfigurationConfiguration of the SnapLogic Server is handled in the file /opt/sna-plogic/config/snapserver.conf while Sidekick configuration is addressed in the file /opt/snaplogic/config/snaplogic.properties. The latter will be automatically configured when the script snaplogic_sidekick_download_config.sh is run to download certificates and configuration. This call  uses basic authentication so it is recommended that you use the https URL to the SnapLogic Server. The configuration file can be edited to change the defaults or to add additional properties.

RegistrationThe property cloud_server is set in snaplogic.properties  for use in registration of Side-kick with a SnapLogic Server. Note that this can be either http or https. For example:

cloud_server=https://server.company.com:8091

OR

cloud_server=http://server.company.com:8088

Heartbeat and Data TransferThe property cloud_proxy is set for use in heartbeat and Component Container data transfers with the SnapLogicServer via Ground and Cloud Proxy in snaplogic.properties on Sidekick. For example:

cloud_proxy=https://server.company.com:8443

This communication must be SSL (not http) and it must be terminated at the SnapLogic Server. Therefore, proper certificates must be installed as discussed in the next section.

The SnapLogic Server can be configured to request the heartbeat of Sidekick by updating the following section of the snapserver.conf file:

[[sidekick]] # Server pings the CC every heartbeat_seconds (set to 0 to disable). heartbeat_seconds = 60

CertificatesSnapLogic generates self-signed certificates.

- 11 -

Page 12: SnapLogic® Sidekick Guide

SnapLogic® Sidekick Guide

Certificates on SnapLogic Server

The certificates for SnapLogic Server are created using the script make_certs.sh and make_agent_certs.sh either during installation or when it is regenerated using the script snap-logic_sidekick_generate_config.sh. It generates the following files:

 l host.cert - X.509 SHA1 Certificate for SnapLogic Server using Private key (RSA512)

 l host.pem - SnapLogic Server Certificate and Private key

 l host.jks - SnapLogic Server Certificate and Private key stored in Java keystore (jks) format

 l textpasswords - Contains various passwords in cleartext including the Sidekick pass-word

Another script, make_agent_certs.sh, is run to generate certificates used for Sidekick SSL communication for heartbeat and data transfer (default port 8443). This is run either during installation or when it is regenerated using the script snaplogic_sidekick_generate_con-fig.sh. It generates the following files:

 l sidekick.jks - host.cert certificate imported into Java keystore format

 l cloud-keystore.jks - X.509 SHA1 Certificate/Private Key for Cloud Proxy

 l cloud-truststore.jks - Truststore that contains Ground Proxy Certificate

 l ground-keystore.jks - X.509 SHA1 Certificate/Private Key for Ground Proxy

 l ground-truststore.jks - Truststore that contains Cloud Proxy Certificate

Certificates on Sidekick

Once Sidekick is installed, the script snaplogic_sidekick_download_config.sh is used to download the certificates and configuration used for this communication. The following .jks files are downloaded from the server:

 l sidekick.jks

 l ground-keystore.jks

 l ground-truststore.jks

 l sidekick_creds - Sidekick credentials used for registration (also available on Server)

Cloud Proxy Validation of Client Certificate

By default, the Cloud Proxy does not validate the Client host certificate in sidekick.jks. To change this behavior to validate the client certificate, /opt/snaplogic/bin/snaplogic_proxy.sh must be changed to add a property -Dsnap.need_client_cert=1.

- 12 -

Page 13: SnapLogic® Sidekick Guide

Configuring Sidekick 1.  Install the appropriate Linux build of Sidekick onto the Sidekick hostusing dpkg –i

<debfile> or rpm –ivh <rpmfile>. Once the package successfully installs, it will print a message to run a download script to download certificates as listed below.

 2.  Navigate to the /bin directory:cd /opt/snaplogic/bin

 3.  Use the su command to login with snapuser:su snapuser./snaplogic_sidekick_download_config.sh -s https://s-naplogicserver.yourcompany.com:8091/

 4.  Type the admin password for the server. The certificates will be downloaded and untarred. Then, Sidekick will be started and it will connect to the cloud instance above.

Enabling Sidekick in DesignerTo enable Sidekick:

 1.  Within Designer, select Server > Configure Sidekick. A new browser tab or window opens with the page Secure Bridge: Not Registered.

 2.  Click Login in the upper-right corner and log in with the admin username and password. If you have configured Sidekick correctly using the certificates downloaded from server, Sidekick will register with the server and you will see the Secure Bridge: Dis-abled page.

 3.  Select the Enabled radio button. The page will update to let you know the Secure Bridge is enabled. You can then click on Info and Logs to see the Sidekick logs. If there are no errors, your Pipelines will now run on Sidekick.

Explicit Proxy SettingIf Sidekick is running on a network with explicit HTTP/HTTPS proxy, you need to add the  fol-lowing line to the snaplogic.properties file in the /opt/snaplogic/config directory on the machine hosting Sidekick:

java_debug=-Dhttp.proxyHost=10.200.10.100 -Dhttp.proxyPort=3128 -Dhttps.proxyHost=10.200.10.100 -Dhttps.proxyPort=3128

where:

 l 10.200.10.100 is the IP address

 l 3128 is the proxy port

Substitute these values with your actual proxy IP and port.

- 13 -

3

Page 14: SnapLogic® Sidekick Guide

SnapLogic® Sidekick Guide

Note: If Sidekick is being used to connect to cloud applications through an explicit proxy, many Snaps are not designed to connect through a proxy.

 

Default PortsThe following ports are the defaults defined for use with the SnapLogic Server and Sidekick.

SnapLogic Server l 8088 - server http

 l 8091 - server https

 l 8089 - cc1 http

 l 8092 - cc1 https

When Sidekick is disabled:

 l 8090 - cc2 http

 l 8093 - cc2 https

When Sidekick is enabled:

 l 8094 - Internal port used by cloud_proxy for server to cloud-proxy communications for forwarding to Sidekick if it is connected

 l 8443 - External port used by cloud_proxy to listen to connections from Sidekick. Once Sidekick connects, cloud_proxy can properly forward server to Sidekick com-munications.

Sidekick l 8095 - cc2 on Sidekick binds to this port

Note: Sidekick needs to be able connect to server_port (usually https port = 8091) and cloud_proxy SSL port (8443).

- 14 -

Page 15: SnapLogic® Sidekick Guide

Automatically Starting and Stopping Sidekick and SnapLogic Server on LinuxThis document explains how to set up SnapLogic Sidekick and SnapLogic Server applications to be run automatically on machine startup or reboot as long as the Linux machine is in multi-user runlevels (2, 3, 4 or 5).

Auto Startup on RedHat-like Distribution (Red Hat, Fedora Core, CentOS, Suse)Automatic Sidekick Startup l To add SnapLogic Sidekick as a Service:

 l Login to the SnapLogic Sidekick Linux machine as root.

 l Change directories as follows:cd /etc/init.d/

 l Create a softlink to the snaplogic.rc file as follows: ln -s /opt/snaplogic/bin/snaplogic.rc snapsidekick

 l Add the softlink to chkconfig management as follows: chkconfig --add snapsidekick

 l To delete SnapLogic Sidekick as a Service:

 l Remove the  service from chkconfig management as follows:chkconfig --del snapsidekick

Automatic Server Startup l To add SnapLogic Server as a Service:

 l Login to SnapLogicserver Linux machine as root

 l Change directories as follows:cd /etc/init.d/

 l Create a softlink to the snapctl.sh file as follows:ln -s /opt/snaplogic/bin/snapctl.sh snaplogic

 l Add the softlink to chkconfig management as follows:chkconfig --add snaplogic

 l To delete SnapLogic Server as a Service:

 l Remove the  service from chkconfig management as follows:chkconfig --del snaplogic

- 15 -

4

Page 16: SnapLogic® Sidekick Guide

SnapLogic® Sidekick Guide

Auto Startup on Debian-like Distribution (Debian, Ubuntu)Automatic Sidekick Startup l To add SnapLogic Sidekick as a Service:

 l Login to SnapLogic Sidekick Linux machine as root.

 l Change directories as follows:cd /etc/init.d/

 l Create a softlink to the snaplogic.rc file as follows: ln -s /opt/snaplogic/bin/snaplogic.rc snapsidekick

 l Add the softlink to update-rc.d with priority 60 on runlevels 2 ,3, 4 and 5 for Start and priority 99 on the same runlevels for Kill as follows:update-rc.d -f snapsidekick start 60 2 3 4 5 . stop 99 2 3 4 5 .

 l To delete SnapLogic Sidekick as a Service:

 l Remove the  service from update-rc.d management as follows:update-rc.d -f snapsidekick remove

Automatic Server Startup l To add SnapLogic Server as a Service:

 l Login to SnapLogicServer Linux machine as root.

 l Change directories as follows:cd /etc/init.d/

 l Create a softlink to the snapctl.sh file as follows:ln -s /opt/snaplogic/bin/snapctl.sh snaplogic

 l Add the softlink to update-rc.d with priority 60 on runlevels 2 ,3, 4 and 5 for Start and priority 99 on the same runlevels for Kill as follows:update-rc.d -f snaplogic start 60 2 3 4 5 . stop 99 2 3 4 5 .

 l To delete SnapLogic Server as a Service:

 l Remove the  service from update-rc.d management as follows:update-rc.d -f snaplogic remove

- 16 -

Page 17: SnapLogic® Sidekick Guide

Sidekick Use CaseThis section of the document describes a complex use case using Sidekick across dis-connected networks.

Scenario: A company has two separate divisions, each on their own network. They want to use SnapLogic to gather data from databases on the local networks.

The  following diagram maps out what this scenario might look like.

The architecture would consist of the following elements:

 l Each division has its own instance of SnapLogic with a Sidekick installed locally to get and update the data on the local server. 

- 17 -

5

Page 18: SnapLogic® Sidekick Guide

SnapLogic® Sidekick Guide

 l A third SnapLogic instance is then used as a primary server to communicate with the division instances.

 l An FTP server is added to the same server with the centralSnapLogic instance and the FTP root directory for the SnapLogic user is the same as the [SNAP_HOME]/data direc-tory for the third SnapLogic Server.

 l The same credentials must be used across all SnapLogic Servers so that Pipelines can access data on other servers.

If you want to copy the data from the database in Division 1 to the other in Division 2: 

 l Division 1: A read-transfer Pipeline is defined on the one division instance to collect the data from the individual database, converts it into a flat file (CSV), and transfer it to the FTP server.

 l Division 2: A transfer-write Pipeline is defined to fetch the data from the FTP server and to write the information to the database.

 l Primary SnapLogic Server: Pipelines are defined to run the Pipelines on Division 1, then run the Pipelines on Division 2 once the first ones are complete.

If you want data from both databases to be merged together and copied back to both data-bases, you would define the read-transfer and transfer-write Pipelines on both Division servers and add merge and filter functionality to the primary server's Pipelines.

- 18 -

Page 19: SnapLogic® Sidekick Guide

Appendix: Python ResourcesWhen Sidekick is in use, Python-based Components and Snaps will not work. Following is a list of Python-Based resources that you will not be able to use with Sidekick.

Note: These lists are based solely on whether the resource was developed in Python or Java. They do not take into account any other compatibility concerns or Snap availability.

Python Components l Compute

 l Date Dimension

 l Execute Resource

 l HTMLFormatter

 l HTTP post/Put

 l RSS Reader

 l RSS Writer

 l XML Write

 l XML Read

Note: Date Operations has both a Java and a Python version of the Component.

Python Snaps l Apache Stats

 l Box.net

 l Google Analytics

 l Magento

 l NetSuite

 l OpenAir

 l SugarCRM

 l YouTube 

 

 

- 19 -

A

Page 20: SnapLogic® Sidekick Guide

- 20 -

SnapLogic® Sidekick Guide

Page 21: SnapLogic® Sidekick Guide

C

certificates

server 12

Sidekick 12

validation of client certificate 12

configuration 13

D

data transfer 11

default ports 14

E

enabling in Designer 13

explicit proxy setting 13

H

heartbeat 11

O

overview 5

R

registration 11

S

starting on Linux 15

stopping on Linux 15

supported platforms 6

U

use case 17

- 21 -

Index

Page 22: SnapLogic® Sidekick Guide

SnapLogic® Sidekick Guide

- 22 -