Connecting to Apache Phoenix
The Lyftrondata Provider for Apache Phoenix connects to Apache Phoenix via the Phoenix Query Server. Set the Server and Port (if different from the default port) properties to connect to Apache Phoenix. The Server property will typically be the host name or IP address of the server hosting Apache Phoenix.
Starting the Server
Different distributions contain different interfaces and means of starting and stopping the Phoenix Query server, along with different default port settings. In most distributions, the server can be started in the background by running the following command: "queryserver.py start". This will require a running instance of HBase and possibly ZooKeeper as well. Please consult your distribution's documentation for further information regarding the Phoenix Query Server.
Authenticating to Apache Phoenix
By default, no authentication will be used (plain). If authentication is configured for your server, set AuthScheme to NEGOTIATE and set the User and Password, if necessary, to authenticate through Kerberos.
This section shows how to use the provider to authenticate to Apache Phoenix using Kerberos.
Authenticating with Kerberos
To authenticate to Apache Phoenix using Kerberos, set the following properties:
- AuthScheme: Set this to NEGOTIATE
- KerberosKDC: Set this to the host name or IP Address of your Kerberos KDC machine.
- KerberosSPN: Set this to the service and host of the Apache Phoenix Kerberos Principal. This will be the value prior to the '@' symbol (for instance, HTTP/MyHost) of the phoenix.queryserver.kerberos.principal of the hbase-site.xml file (for instance, HTTP/MyHost@EXAMPLE.COM).
Retrieve the Kerberos Ticket
You can use one of the following options to retrieve the required Kerberos ticket.
MIT Kerberos Credential Cache File
This option enables you to use the MIT Kerberos Ticket Manager or kinit command to get tickets. Note that you won't need to set the User or Password connection properties with this option.
- Ensure that you have an environment variable created called KRB5CCNAME.
- Set the KRB5CCNAME environment variable to a path pointing to your credential cache file (for instance, C:\krb_cache\krb5cc_0 or /tmp/krb5cc_0). This file will be created when generating your ticket with MIT Kerberos Ticket Manager.
- To obtain a ticket, open the MIT Kerberos Ticket Manager application, click Get Ticket, enter your principal name and password, then click OK. If successful, ticket information will appear in Kerberos Ticket Manager and will now be stored in the credential cache file.
- Now that the credential cache file has been created, the provider will use the cache file to obtain the kerberos ticket to connect to Apache Phoenix.
As an alternative to setting the KRB5CCNAME environment variable, you can directly set the file path using the KerberosTicketCache property. When set, the provider will use the specified cache file to obtain the kerberos ticket to connect to Apache Phoenix.
If the KRB5CCNAME environment variable has not been set, you can retrieve a Kerberos ticket using a Keytab File. To do this, set the User property to the desired username and set the KerberosKeytabFile property to a file path pointing to the keytab file associated with the user.
User and Password
If both the KRB5CCNAME environment variable and the KerberosKeytabFile property have not been set, you can retrieve a ticket using a User and Password combination. To do this, set the User and Password properties to the user/password combo that you use to authenticate with Apache Phoenix.
More complex Kerberos environments may require cross-realm authentication where multiple realms and KDC servers are used (e.g. where one realm/KDC is used for user authentication and another realm/KDC used for obtaining the service ticket).
In such an environment, the KerberosRealm and KerberosKDC properties can be set to the values required for user authentication. The KerberosServiceRealm and KerberosServiceKDC properties can be set to the values required to obtain the service ticket.
Connecting Through a Firewall or Proxy
Set the following properties: Set FirewallType, FirewallServer, and FirewallPort. To tunnel the connection, set FirewallType to TUNNEL. To authenticate specify FirewallUser and FirewallPassword. To authenticate to a SOCKS proxy, additionally set FirewallType to SOCKS5.
Troubleshooting the Connection
To show provider activity from query execution to network traffic, use Logfile and Verbosity. The examples of common connection errors below show how to use these properties to get more context. Contact the support team for help tracing the source of an error or circumventing a performance issue.
- Authentication errors: Typically, recording a Logfile at Verbosity 4 is necessary to get full details on an authentication error.
- Queries time out: A server that takes too long to respond will exceed the provider's client-side timeout. Often, setting the Timeout property to a higher value will avoid a connection error. Another option is to disable the timeout by setting the property to 0. Setting Verbosity to 2 will show where the time is being spent.
The certificate presented by the server cannot be validated: This error indicates that the provider cannot validate the server's certificate through the chain of trust. (If you are using a self-signed certificate, there is only one certificate in the chain).
To resolve this error, you must verify yourself that the certificate can be trusted and specify to the provider that you trust the certificate. One way you can specify that you trust a certificate is to add the certificate to the trusted system store; another is to set SSLServerCert.
Enabling multiple schemas
By default, the Lyftrondata ADO.NET Provider for Apache Phoenix 2019 will not use multiple schemas. The driver can be configured to work with other schemas if EnableSchemas is set to true. The necessary changes must be made on the server-side of HBase and ApachePhoenix. Please consult the docs for more information.