Move ODBC documentation to `elasticsearch` repository (#36955)

docs/reference/sql/endpoints/index.asciidoc

@@ -2,4 +2,5 @@ include::rest.asciidoc[]
 include::translate.asciidoc[]
 include::cli.asciidoc[]
 include::jdbc.asciidoc[]
+include::odbc.asciidoc[]
 include::client-apps/index.asciidoc[]

docs/reference/sql/endpoints/odbc.asciidoc

@@ -0,0 +1,29 @@
+:es: Elasticsearch
+:es-sql: {es} SQL
+:version: 6.5.0
+:product: {es-sql} ODBC Driver
+
+[role="xpack"]
+[testenv="platinum"]
+[[sql-odbc]]
+== SQL ODBC
+
+[[sql-odbc-overview]]
+[float]
+=== Overview
+
+experimental[]
+
+{product} is a feature-rich 3.80 ODBC driver for {es}.
+It is a core level driver, exposing all of the functionality accessible through the {es}'s SQL ODBC API, converting ODBC calls into
+{es-sql}.
+
+* <<sql-odbc-installation, Driver installation>>
+* <<sql-odbc-setup, Configuration>>
+* <<sql-odbc-applications, ODBC client applications>>
+
+include::odbc/installation.asciidoc[]
+include::odbc/configuration.asciidoc[]
+include::odbc/applications.asciidoc[]
+
+// vim: set noet fenc=utf-8 ff=dos sts=0 sw=4 ts=4 tw=138

docs/reference/sql/endpoints/odbc/applications-excel.asciidoc

@@ -0,0 +1,63 @@
+[role="xpack"]
+[testenv="platinum"]
+[[sql-odbc-applications-excel]]
+=== Microsoft Excel
+
+experimental[]
+
+[quote, https://www.techopedia.com/definition/5430/microsoft-excel]
+____
+https://products.office.com/en/excel[Microsoft Excel] is a software program [...] that allows users to organize, format and calculate data
+with formulas using a spreadsheet system.
+____
+
+==== Prerequisites
+
+* Microsoft Office 2016 or higher
+* {product}
+* A preconfigured User or System DSN (see <<sql-odbc-setup>> section on how to configure a DSN).
+
+==== Load data into a spreadsheet
+
+First, you'll need to choose ODBC as the source to load data from. To do so, click on the _Data_ tab, then _New Query_ button, in the
+drop-down menu expand _From Other Sources_, then choose _From ODBC_:
+
+[[apps_excel_fromodbc]]
+.ODBC as data source
+image:images/sql/odbc/apps_excel_fromodbc.png[]
+
+This will open a new window with a drop down menu populated with the DSNs that Excel found on the system. Choose a DSN configured to
+connect to your {es} instance and press the _OK_ button:
+
+[[apps_excel_dsn]]
+.Choose a DSN
+image:images/sql/odbc/apps_excel_dsn.png[]
+
+This will lead to a new window, allowing the user to input the connection credentials.
+
+A username might be required by Excel even if the {es} instance has no security enabled. Providing a bogus username with no password in
+this case will not hinder the connectivity. Note however that Excel will cache these credentials (so in case you do have security enabled,
+you won't be prompted for the credentials a second time).
+
+Fill in the username and the password and press
+_Connect_.
+
+[[apps_excel_cred]]
+.Provide connection credentials
+image:images/sql/odbc/apps_excel_cred.png[]
+
+Once connected, Excel will read {es}'s catalog and offer the user a choice of tables (indices) to load data from. Clicking on one of the
+tables will load a preview of the data within:
+
+[[apps_excel_picktable]]
+.Pick table to load
+image:images/sql/odbc/apps_excel_picktable.png[]
+
+Now click the _Load_ button, which will have Excel load all the data from the table into a spreadsheet:
+
+[[apps_excel_loaded]]
+.Data loaded in spreadsheet
+image:images/sql/odbc/apps_excel_loaded.png[]
+
+
+// vim: set noet fenc=utf-8 ff=dos sts=0 sw=4 ts=4 tw=138 columns=140

docs/reference/sql/endpoints/odbc/applications-microstrat.asciidoc

@@ -0,0 +1,97 @@
+[role="xpack"]
+[testenv="platinum"]
+[[sql-odbc-applications-microstrat]]
+=== MicroStrategy Desktop
+
+experimental[]
+
+[quote, https://www.microstrategy.com/us/resources/library/videos/new-microstrategy-desktop]
+____
+https://www.microstrategy.com/us/get-started/desktop[MicroStrategy Desktop] is a free data discovery tool that helps people bring data to
+life using powerful self-service analytics.
+____
+
+==== Prerequisites
+
+* MicroStrategy Desktop 11 or higher
+* {product}
+* A preconfigured User or System DSN (see <<sql-odbc-setup>> section on how to configure a DSN).
+
+==== Data loading
+
+To use the {product} to load data into MicroStrategy Desktop perform the following steps in sequence.
+
+. Create a New Dossier
++
+Once the application is launched, you'll first need to create a _New Dossier_:
++
+[[apps_microstrat_newdossier]]
+image:images/sql/odbc/apps_microstrat_newdossier.png[]
++
+. New Data
++
+To import into the _New Dossier_ just opened, press on the _New Data_ button in the _DATASETS_ column:
++
+[[apps_microstrat_newdata]]
+image:images/sql/odbc/apps_microstrat_newdata.png[]
++
+. Access data from Tables
++
+This opens a new window that allows to choose the source to load data from. Click on the _Databases_ icon:
++
+[[apps_microstrat_databases]]
+image:images/sql/odbc/apps_microstrat_databases.png[]
++
+. New Data Source
++
+In the newly opened _Import from Table - Select_ window, click on the *+* button to the right of _DATA SOURCES_ item:
++
+[[apps_microstrat_newds]]
+image:images/sql/odbc/apps_microstrat_newds.png[]
++
+. Data Source
++
+In the _Data Source_ window, tick the radio button for _DSN Data Sources_. In the _DSN_ drop-down box, choose the name of the DSN that you
+have previously configured. For the _Version_, chose _Generic DBMS_.
++
+Input a user name and password in the provided fields.
+Note that the application requires them irrespective of the fact that they might already be part of the previously configured DSN and the
+new input will take precedence over those.
++
+Finally, give a name to the application-specific data source you're just configuring:
++
+[[apps_microstrat_dsn]]
+image:images/sql/odbc/apps_microstrat_dsn.png[]
++
+. Select Import Options
++
+Choosing an import methodology follows. You can pick any of the options; we'll exemplify the _Select Tables_ option:
++
+[[apps_microstrat_tables]]
+image:images/sql/odbc/apps_microstrat_tables.png[]
++
+. Import from Table - Select
++
+The data source you've named two steps before is now listed in the _DATA SOURCES_ column. Clicking on its name triggers the
+application to query the {es} instance configured in the DSN and list the tables available within:
++
+[[apps_microstrat_loadtable]]
+image:images/sql/odbc/apps_microstrat_loadtable.png[]
++
+. Data Access Mode
++
+Choose a table to load data from and press the _Finish_ button. When doing so, the application offers to choose a loading methdology.
+You can choose whichever, we'll exemplify the _Connect Live_ way:
++
+[[apps_microstrat_live]]
+image:images/sql/odbc/apps_microstrat_live.png[]
++
+. Visualize the data
++
+From the _DATASETS_ column you can choose what table columns (or index fields) to visualize:
++
+[[apps_microstrat_visualize]]
+image:images/sql/odbc/apps_microstrat_visualize.png[]
+
+
+// vim: set noet fenc=utf-8 ff=dos sts=0 sw=4 ts=4 tw=138 columns=140

docs/reference/sql/endpoints/odbc/applications-powerbi.asciidoc

@@ -0,0 +1,55 @@
+[role="xpack"]
+[testenv="platinum"]
+[[sql-odbc-applications-powerbi]]
+=== Microsoft Power BI Desktop
+
+experimental[]
+
+[quote, https://powerbi.microsoft.com/en-us/what-is-power-bi/]
+____
+https://powerbi.microsoft.com/en-us/desktop/[Power BI] is a business analytics solution that lets you visualize your data and share
+insights across your organization, or embed them in your app or website.
+____
+
+==== Prerequisites
+
+* Microsoft Power BI Desktop 2.63 or higher
+* {product}
+* A preconfigured User or System DSN (see <<sql-odbc-setup>> section on how to configure a DSN).
+
+==== Data loading
+
+First, you'll need to choose ODBC as the source to load data from. Once launched, click on the _Get Data_ button (under _Home_ tab), then
+on the _More..._ button at the bottom of the list:
+
+[[apps_pbi_fromodbc1]]
+.Get Data / More...
+image:images/sql/odbc/apps_pbi_fromodbc1.png[]
+
+In the new opened window scroll at the bottom of the _All_ list and select the _ODBC_ entry, then click on the _Connect_ button:
+
+[[apps_pbi_fromodbc2]]
+.ODBC / Connect
+image:images/sql/odbc/apps_pbi_fromodbc2.png[]
+
+This will replace current window with a new _From ODBC_ one, where you'll have to select a previously configured DSN:
+
+[[apps_pbi_dsn]]
+.Choose a DSN
+image:images/sql/odbc/apps_pbi_dsn.png[]
+
+Once connected Power BI will read {es}'s catalog and offer the user a choice of tables (indices) to load data from. Clicking on one of the
+tables will load a preview of the data within:
+
+[[apps_pbi_picktable]]
+.Pick table to load
+image:images/sql/odbc/apps_pbi_picktable.png[]
+
+Now tick the chosen table and click on the _Load_ button. Power BI will now load and anlyze the data, populating a list with the available
+columns. These can now be used to build the desired visualisation:
+
+[[apps_pbi_loaded]]
+.Visualize the data
+image:images/sql/odbc/apps_pbi_loaded.png[]
+
+// vim: set noet fenc=utf-8 ff=dos sts=0 sw=4 ts=4 tw=138 columns=140

docs/reference/sql/endpoints/odbc/applications-ps1.asciidoc

@@ -0,0 +1,50 @@
+[role="xpack"]
+[testenv="platinum"]
+[[sql-odbc-applications-ps1]]
+=== Microsoft PowerShell
+
+experimental[]
+
+[quote, https://docs.microsoft.com/en-us/powershell/scripting/powershell-scripting]
+____
+https://docs.microsoft.com/en-us/powershell/[PowerShell] is a task-based command-line shell and scripting language built on .NET.
+____
+
+PowerShell is available on all recent Windows Desktop OSes. It also has embedded ODBC support, thus offering a quick and accessible way to
+connect to {es}.
+
+==== Prerequisites
+
+* Microsoft PowerShell
+* {product}
+* A preconfigured User or System DSN (see <<sql-odbc-setup>> section on how to configure a DSN).
+
+==== Writing a script
+
+While putting the following instructions into a script file is not an absolute requirement, doing so will make it easier to extend and
+reuse. The following instructions exemplify how to execute a simple SELECT query from an existing index in your {es} instance, using a DSN
+configured in advance. Open a new file, `select.ps1`, and place the following instructions in it:
+
+["source","powershell",subs="attributes,callouts"]
+--------------------------------------------
+$connectstring = "DSN=Local Elasticsearch;"
+$sql = "SELECT * FROM library"
+
+$conn = New-Object System.Data.Odbc.OdbcConnection($connectstring)
+$conn.open()
+$cmd = New-Object system.Data.Odbc.OdbcCommand($sql,$conn)
+$da = New-Object system.Data.Odbc.OdbcDataAdapter($cmd)
+$dt = New-Object system.Data.datatable
+$null = $da.fill($dt)
+$conn.close()
+$dt
+--------------------------------------------
+
+Now open a PowerShell shell and simply execute the script:
+
+[[apps_excel_exed]]
+.Run SQL in PowerShell
+image:images/sql/odbc/apps_ps_exed.png[]
+
+
+// vim: set noet fenc=utf-8 ff=dos sts=0 sw=4 ts=4 tw=138 columns=140

docs/reference/sql/endpoints/odbc/applications-qlik.asciidoc

@@ -0,0 +1,85 @@
+[role="xpack"]
+[testenv="platinum"]
+[[sql-odbc-applications-qlik]]
+=== Qlik Sense Desktop
+
+experimental[]
+
+[quote, https://help.qlik.com/en-US/sense/February2018/Subsystems/Hub/Content/Introduction/at-a-glance.htm]
+____
+https://www.qlik.com/us/try-or-buy/download-qlik-sense[Qlik Sense Desktop] is a Windows application that gives individuals the opportunity
+to use Qlik Sense and create personalized, interactive data visualizations, reports, and dashboards from multiple data sources with
+drag-and-drop ease.
+____
+
+==== Prerequisites
+
+* Qlik Sense Desktop November 2018 or higher
+* {product}
+* A preconfigured User or System DSN (see <<sql-odbc-setup>> section on how to configure a DSN).
+
+==== Data loading
+
+To use the {product} to load data into Qlik Sense Desktop perform the following steps in sequence.
+
+. Create new app
++
+Once the application is launched, you'll first need to click on the _Create new app_ button:
++
+[[apps_qlik_newapp]]
+image:images/sql/odbc/apps_qlik_newapp.png[]
++
+. Name app
++
+...then give it a name,
++
+[[apps_qlik_create]]
+image:images/sql/odbc/apps_qlik_create.png[]
++
+. Open app
++
+...and then open it:
++
+[[apps_qlik_open]]
+image:images/sql/odbc/apps_qlik_open.png[]
++
+. Add data to your app
++
+Start configuring the source to load data from in the newly created app:
++
+[[apps_qlik_adddata]]
+image:images/sql/odbc/apps_qlik_adddata.png[]
++
+. Load from ODBC
++
+You'll be given a choice of sources to select. Click on the _ODBC_ icon:
++
+[[apps_qlik_odbc]]
+image:images/sql/odbc/apps_qlik_odbc.png[]
++
+. Choose DSN
++
+In the _Create new connection (ODBC)_ dialog, click on the DSN name that you have previously configured for your {es} instance:
++
+[[apps_qlik_dsn]]
+image:images/sql/odbc/apps_qlik_dsn.png[]
++
+Provide a username and password in the respective fields, if authentication is enabled on your instance and if these are not already part
+of the DSN. Press the _Create_ button.
++
+. Select source table
++
+The application will now connect to the {es} instance and query the catalog information, presenting you with a list of tables that you can
+load data from:
++
+[[apps_qlik_selecttable]]
+image:images/sql/odbc/apps_qlik_selecttable.png[]
++
+. Visualize the data
++
+Press on the _Add data_ button and customize your data visualization:
++
+[[apps_qlik_visualize]]
+image:images/sql/odbc/apps_qlik_visualize.png[]
+
+// vim: set noet fenc=utf-8 ff=dos sts=0 sw=4 ts=4 tw=138 columns=140

docs/reference/sql/endpoints/odbc/applications-tableau.asciidoc

@@ -0,0 +1,49 @@
+[role="xpack"]
+[testenv="platinum"]
+[[sql-odbc-applications-tableau]]
+=== Tableau Desktop
+
+experimental[]
+
+[quote, https://www.tableau.com/products/what-is-tableau]
+____
+https://www.tableau.com/products/desktop[Tableau] is the most powerful, secure, and flexible end-to-end analytics platform
+for your data.
+____
+
+==== Prerequisites
+
+* Tableau 2018 or higher
+* {product}
+* A preconfigured User or System DSN (see <<sql-odbc-setup>> section on how to configure a DSN).
+
+==== Data loading
+
+First, you'll need to choose ODBC as the source to load data from. Once launched, click on the _More..._ menu item and in the expanded
+list of connectors, choose _Other Databases (ODBC)_:
+
+[[apps_tableau_fromodbc]]
+.ODBC as data source
+image:images/sql/odbc/apps_tableau_fromodbc.png[]
+
+In the new connection window that appears, select the previously configured DSN that will connect to the desired {es} instance. Press the
+_Connect_ button. In case credentials are needed, a new windows - driver's DSN editor - will be launched and you'll need to provide the
+_Username_ and _Password_ in the respective fields. (Note that these will not be stored as part of the DSN, but only remembered for the
+duration of the session).
+If the connection is successful, the _Connection Attributes_ section of the connection window is populated with the respective details;
+press the _Sign In_ button next:
+
+[[apps_tableau_connd]]
+.Authenticate and sign in
+image:images/sql/odbc/apps_tableau_connd.png[]
+
+In Tableau Desktop's main window then choose the name of {es} instance as the _Database_, select one table that you'd like to load from
+the list (click on the magnifying glass icon to have them all shown), drag the table over the work area, then click the _Update Now_
+button to load a preview of the table:
+
+[[apps_tableau_loaded]]
+.Data loaded
+image:images/sql/odbc/apps_tableau_loaded.png[]
+
+
+// vim: set noet fenc=utf-8 ff=dos sts=0 sw=4 ts=4 tw=138 columns=140

docs/reference/sql/endpoints/odbc/applications.asciidoc

@@ -0,0 +1,32 @@
+[role="xpack"]
+[testenv="platinum"]
+[[sql-odbc-applications]]
+=== ODBC client applications
+
+experimental[]
+
+Thanks to a standardized API, a broad range of third-party ODBC-enabled applications can access {es} using {product}.
+This section will collect alphabetically an increasing list of such applications along with the configuration steps that need to be taken
+within them.
+
+* <<sql-odbc-applications-excel, Microsoft Excel>>
+* <<sql-odbc-applications-powerbi, Microsoft Power BI Desktop>>
+* <<sql-odbc-applications-ps1, Microsoft PowerShell>>
+* <<sql-odbc-applications-microstrat, MicroStrategy Desktop>>
+* <<sql-odbc-applications-qlik, Qlik Sense Desktop>>
+* <<sql-odbc-applications-tableau, Tableau Desktop>>
+
+NOTE: Each application has its own requirements and licensing; these are outside the scope of this documentation which only covers the
+configuration aspect of integration with {es-sql}.
+
+WARNING: The support for applications implementing the ODBC 2.x standard and prior is currently limited.
+
+include::applications-excel.asciidoc[]
+include::applications-powerbi.asciidoc[]
+include::applications-ps1.asciidoc[]
+include::applications-microstrat.asciidoc[]
+include::applications-qlik.asciidoc[]
+include::applications-tableau.asciidoc[]
+
+
+// vim: set noet fenc=utf-8 ff=dos sts=0 sw=4 ts=4 tw=138 columns=140

docs/reference/sql/endpoints/odbc/configuration.asciidoc

@@ -0,0 +1,268 @@
+[role="xpack"]
+[testenv="platinum"]
+[[sql-odbc-setup]]
+=== Configuration
+
+experimental[]
+
+Once the driver has been installed, in order for an application to be able to connect to {es} through ODBC, a set of configuration parameters must be provided to the driver. Depending on the application, there are generally three ways of providing these parameters:
+
+* through a connection string;
+* using a User DSN or System DSN;
+* through a File DSN.
+
+DSN (_data source name_) is a generic name given to the set of parameters an ODBC driver needs to connect to a database.
+
+We will refer to these parameters as _connection parameters_ or _DSN_ (despite some of these parameters configuring some other aspects of a driver's functions; e.g. logging, buffer sizes...).
+
+Using a DSN is the most widely used, simplest and safest way of performing the driver configuration. Constructing a connection string, on the other hand, is the most crude way and consequently the least common method.
+
+We will focus on DSN usage only.
+
+[[data-source-administrator]]
+==== 1. Launching ODBC Data Source Administrator
+
+For DSN management, ODBC provides the _ODBC Data Source Administrator_ application, readily installed on all recent desktop Windows operating systems.
+
+- The 32-bit version of the Odbcad32.exe file is located in the `%systemdrive%\Windows\SysWoW64` folder.
+- The 64-bit version of the Odbcad32.exe file is located in the `%systemdrive%\Windows\System32` folder.
+
+To launch it, open the search menu - _Win + S_ - and type "ODBC Data Sources (64-bit)" or "ODBC Data Sources (32-bit)" and press _Enter_:
+
+[[launch_administrator]]
+.Launching ODBC Data Source Administrator
+image:images/sql/odbc/launch_administrator.png[]
+
+Once launched, you can verify that the driver was installed correctly by clicking on the _Drivers_ tab of the ODBC Data Source Administrator and checking that _Elasticsearch Driver_ is present in the list of installed drivers.
+
+You should also see the version number of the installed driver.
+
+[[administrator_drivers]]
+.Drivers tab
+image:images/sql/odbc/administrator_drivers.png[]
+
+[[dsn-configuration]]
+==== 2. Configure a DSN
+The next step is to configure a DSN. You can choose between the following options mapped on the first three tabs of the Administrator application:
+
+* User DSN
++
+The connections configured under this tab are only available to the currently logged in user. Each of these DSNs are referred to by a chosen arbitrary name (typically a host or cluster name).
++
+The actual set of parameters making up the DSN is stored through the driver in the system registry. Thus, a user will later only need to provide an application with the DSN name in order to connect to the configured {es} instance.
++
+* System DSN
++
+Similar to a User DSN, except that the connections configured under this tab will be available to all the users configured on the system.
+* File DSN
++
+This tab contains functionality that will allow to have one set of connection parameters written into a file, rather then the Registry.
++
+Such a file can be then shared among multiple systems and the user will need to specify the path to it, in order to have the application connect to the configured {es} instance.
+
+The configuration steps are similar for all the above points. Following is an example of configuring a System DSN.
+
+[float]
+===== 2.1 Launch {product} DSN Editor
+Click on the _System DSN_ tab, then on the _Add..._ button:
+
+[[system_add]]
+.Add a new DSN
+image:images/sql/odbc/administrator_system_add.png[]
+
+A new window will open, listing all available installed drivers. Click on _{es} Driver_, to highlight it, then on the _Finish_ button:
+
+[[launch_editor]]
+.Launch the DSN Editor
+image:images/sql/odbc/administrator_launch_editor.png[]
+
+This action closes the previously opened second window and open a new one instead, {product}'s DSN Editor:
+
+[[dsn_editor]]
+.{product} DSN Editor
+image:images/sql/odbc/dsn_editor_basic.png[]
+
+This new window has three tabs, each responsible for a set of configuration parameters, as follows.
+
+[float]
+===== 2.2 Connection parameters
+This tab allows configuration for the following items:
+
+* Name
++
+This is the name the DSN will be referred by.
++
+NOTE: The characters available for this field are limited to the set permitted for a Registry key.
++
+Example: _localhost_
++
+* Description
++
+This field allows a arbitrary text; generally used for short notes about the configured connection.
++
+Example: _Clear-text connection to the local [::1]:9200._
++
+* Hostname
++
+This field requires an IP address or a resolvable DNS name of the {es} instance that the driver will connect to.
++
+Example: _::1_
++
+* Port
++
+The port on which the {es} listens on.
++
+NOTE: If left empty, the default *9200* port number will be used.
++
+* Username, Password
++
+If security is enabled, these fields will need to contain the credentials of the user configured to access the REST SQL endpoint.
+
+At a minimum, the _Name_ and _Hostname_ fields must be provisioned, before the DSN can be saved.
+
+WARNING: Connection encryption is enabled by default. This will need to be changed if connecting to a SQL API endpoint with no cryptography enabled.
+
+[float]
+===== 2.3 Cryptography parameters
+One of the following SSL options can be chosen:
+
+* Disabled. All communications unencrypted.
++
+The communication between the driver and the {es} instance is performed over a clear-text connection.
++
+WARNING: This setting can expose the access credentials to a 3rd party intercepting the network traffic and is not recommended.
++
+* Enabled. Certificate not validated.
++
+The connection encryption is enabled, but the certificate of the server is not validated.
++
+This is currently the default setting.
++
+NOTE: This setting allows a 3rd party to act with ease as a man-in-the-middle and thus intercept all communications.
++
+* Enabled. Certificate is validated; hostname not validated.
++
+The connection encryption is enabled and the driver verifies that server's certificate is valid, but it does *not* verify if the
+certificate is running on the server it was meant for.
++
+NOTE: This setting allows a 3rd party that had access to server's certificate to act as a man-in-the-middle and thus intercept all the
+communications.
++
+* Enabled. Certificate is validated; hostname validated.
++
+The connection encryption is enabled and the driver verifies that both the certificate is valid, as well as that it is being deployed on
+the server that the certificate was meant for.
++
+* Enabled. Certificate identity chain validated.
++
+This setting is equivalent to the previous one, with one additional check against certificate's revocation. This offers the strongest
+security option and is the recommended setting for production deployments.
++
+* Certificate File
++
+In case the server uses a certificate that is not part of the PKI, for example usaing a self-signed certificate, you can configure the path to a X.509 certificate file that will be used by the driver to validate server's offered certificate.
++
+The driver will only read the contents of the file just before a connection is attempted. See <<connection_testing>> section further on how to check the validity of the provided parameters.
++
+If using the file browser to locate the certificate - by pressing the _Browse..._ button - only files with _.pem_ and _.der_ extensions
+will be considered by default. Choose _All Files (\*.*)_ from the drop down, if your file ends with a different extension:
++
+[[dsn_editor_cert]]
+.Certificate file browser
+image:images/sql/odbc/dsn_editor_security_cert.png[]
+
+[float]
+===== 2.4 Logging parameters
+For troubleshooting purposes, the {product} offers functionality to log the API calls that an application makes; this is enabled in the Administrator application:
+
+[[administrator_tracing]]
+.Enable Application ODBC API logging
+image:images/sql/odbc/administrator_tracing.png[]
+
+However, this only logs the ODBC API calls made by the application into the _Driver Manager_ and not those made by the _Driver Manager_ into the driver itself. To enable logging of the calls that the driver receives, as well as internal driver processing events, you can enable driver's logging on Editor's _Logging_ tab:
+
+* Enable Logging?
++
+Ticking this will enable driver's logging. A logging directory is also mandatory when this option is enabled (see the next option).
+However the specified logging directory will be saved in the DSN if provided, even if logging is disabled.
++
+* Log Directory
++
+Here is to specify which directory to write the log files in.
++
+NOTE: The driver will create *one log file per connection*, for those connections that generate logging messages.
++
+* Log Level
++
+Configure the verbosity of the logs.
++
+[[administrator_logging]]
+.Enable driver logging
+image:images/sql/odbc/dsn_editor_logging.png[]
++
+When authentication is enabled, the password will be redacted from the logs.
+
+NOTE: Debug-logging can quickly lead to the creation of many very large files and generate significant processing overhead. Only enable if
+instructed so and preferably only when fetching low volumes of data.
+
+[float]
+[[connection_testing]]
+===== 2.5 Testing the connection
+Once the _Hostname_, the _Port_ (if different from implicit default) and the SSL options are configured, you can test if the provided
+parameters are correct by pressing the _Test Connection_ button. This will instruct the driver to connect to the {es} instance and perform
+a simple SQL test query. (This will thus require a running {es} instance with the SQL plugin enabled.)
+
+[[dsn_editor_conntest]]
+.Connection testing
+image:images/sql/odbc/dsn_editor_conntest.png[]
+
+NOTE: When connection testing, all the configured parameters are taken into account, including the logging configuration. This will allow
+early detection of potential file/directory access rights conflicts.
+
+See <<alternative_logging>> section further for an alternative way of configuring the logging.
+
+[[available-dsn]]
+==== 3. DSN is available
+Once everything is in place, pressing the _Save_ button will store the configuration into the chosen destination (Registry or file).
+
+Before saving a DSN configuration the provided file/directory paths are verified to be valid on the current system. The DSN editor
+will however not verify in any way the validity or reachability of the configured _Hostname_ : _Port_. See <<connection_testing>>
+for an exhaustive check.
+
+If everything is correct, the name of the newly created DSN will be listed as available to use:
+
+[[system_added]]
+.Connection added
+image:images/sql/odbc/administrator_system_added.png[]
+
+[[alternative_logging]]
+==== Alternative logging configuration
+
+Due to the specification of the ODBC API, the driver will receive the configured DSN parameters - including the logging ones - only once a
+connection API is invoked (such as _SQLConnect_ or _SQLDriverConnect_). The _Driver Manager_ will however always make a set of API calls
+into the driver before attempting to establish a connection. To capture those calls as well, one needs to pass logging configuration
+parameters in an alternative way. The {product} will use an environment variable for this purpose.
+
+Configuring an environment variable is OS specific and not detailed in this guide. Whether the variable should be configured system-wide
+or user-specific depends on the way the ODBC-enabled application is being run and if logging should affect the current user only or not.
+
+The definition of the environment variable needs to be done as follows:
+
+* Name: _ESODBC_LOG_DIR_
+
+* Value: [path](?[level]), where:
++
+[path] is the path to the directory where the log files will be written into;
++
+[level] is optional and can take one of the following values: _debug_, _info_, _warn_, _error_; if not provided, _debug_ is assumed.
+
+[[env_var_logging]]
+.Logging environment variable
+image:images/sql/odbc/env_var_log.png[]
+
+NOTE: When enabling the logging through the environment variable, the driver will create *one log file per process*.
+
+Both ways of configuring the logging can coexist and both can use the same destination logging directory. However, one logging message
+will only be logged once, the connection logging taking precedence over the environment variable logging.
+
+// vim: set noet fenc=utf-8 ff=dos sts=0 sw=4 ts=4 tw=138

docs/reference/sql/endpoints/odbc/installation.asciidoc

@@ -0,0 +1,163 @@
+[role="xpack"]
+[testenv="platinum"]
+[[sql-odbc-installation]]
+=== Driver installation
+
+experimental[]
+
+The {product} can be installed on Microsoft Windows using an MSI package. The installation process is simple and is composed of standard MSI wizard steps.
+
+[[prerequisites]]
+==== Installation Prerequisites
+
+Before you install the {product} you need to meet the following prerequisites;
+
+* Windows 10 64 bit _or_ Windows Server 2016 64 bit operating system
+* .NET Framework 4.0 full - https://www.microsoft.com/en-au/download/details.aspx?id=17718
+* Microsoft Visual C++ Redistributable for Visual Studio 2017 - https://support.microsoft.com/en-au/help/2977003/the-latest-supported-visual-c-downloads
+- The 64 bit driver requires the x64 redistributable (this also installs the components needed for the 32 bit driver)
+- The 32 bit driver requires the x86 redistributable
+* Elevated privileges (administrator) for the User performing the installation
+
+If you fail to meet any of the prerequisites the installer will show an error message and abort the installation.
+
+NOTE: It is not possible to inline upgrade using the MSI. In order to upgrade, you will first have to uninstall the old driver and then install the new driver.
+
+[[download]]
+==== Download the `.msi` package(s)
+
+Download the `.msi` package for {product} {version} from:
+https://www.elastic.co/downloads/odbc-client
+
+There are two versions of the installer available:
+
+- *32 bit driver (x86)* for use with the Microsoft Office 2016 suite of applications; notably Microsoft Excel and Microsoft Access and other 32 bit based programs.
+- *64 bit driver (x64)* recommended for use with all other applications.
+
+Users should consider downloading and installing both the 32 and 64 bit drivers for maximum compatibility across applications installed on their system.
+
+[[installation-gui]]
+==== Installation using the graphical user interface (GUI)
+
+Double-click the downloaded `.msi` package to launch a GUI wizard that will guide you through the installation process.
+
+You will first be presented with a welcome screen:
+
+image::images/sql/odbc/installer_started.png[Installer Welcome Screen]
+
+Clicking *Next* will present the End User License Agreement. You will need to accept the license agreement in order to continue the installation.
+
+image::images/sql/odbc/installer_accept_license.png[Installer EULA Screen]
+
+The following screen allows you to customise the installation path for the Elasticsearch ODBC driver files.
+
+NOTE: The default installation path is of the format: *%ProgramFiles%\Elastic\ODBCDriver{backslash}{version}*
+
+image::images/sql/odbc/installer_choose_destination.png[Installer Driver Path]
+
+You are now ready to install the driver.
+
+NOTE: You will require elevated privileges (administrator) for installation.
+
+image::images/sql/odbc/installer_ready_install.png[Installer Begin]
+
+Assuming the installation takes place without error you should see progress screen, followed by the finish screen:
+
+image::images/sql/odbc/installer_installing.png[Installer Installing]
+
+On the finish screen you can launch the ODBC Data Source Administration screen by checking the dialog checkbox. This will automatically launch the configuration screen on close (either 32 bit or 64 bit) where you can configure a DSN.
+
+image::images/sql/odbc/installer_finish.png[Installer Complete]
+
+As with any MSI installation package, a log file for the installation process can be found within the `%TEMP%` directory, with a randomly generated name adhering to the format `MSI<random>.LOG`.
+
+If you encounter an error during installation we would encourage you to open an issue https://github.com/elastic/elasticsearch-sql-odbc/issues, attach your installation log file and provide additional details so we can investigate.
+
+[[installation-cmd]]
+==== Installation using the command line
+
+NOTE: The examples given below apply to installation of the 64 bit MSI package. To acheive the same result with the 32 bit MSI package you would instead use the filename suffix `windows-x86.msi`
+
+The `.msi` can also be installed via the command line. The simplest installation using the same defaults as the GUI is achieved by first navigating to the download directory, then running:
+
+["source","sh",subs="attributes,callouts"]
+--------------------------------------------
+msiexec.exe /i esodbc-{version}-windows-x86_64.msi /qn
+--------------------------------------------
+
+By default, `msiexec.exe` does not wait for the installation process to complete, since it runs in the Windows subsystem. To wait on the process to finish and ensure that `%ERRORLEVEL%` is set accordingly, it is recommended to use `start /wait` to create a process and wait for it to exit:
+
+["source","sh",subs="attributes,callouts"]
+--------------------------------------------
+start /wait msiexec.exe /i esodbc-{version}-windows-x86_64.msi /qn
+--------------------------------------------
+
+As with any MSI installation package, a log file for the installation process can be found within the `%TEMP%` directory, with a randomly generated name adhering to the format `MSI<random>.LOG`. The path to a log file can be supplied using the `/l` command line argument
+
+["source","sh",subs="attributes,callouts"]
+--------------------------------------------
+start /wait msiexec.exe /i esodbc-{version}-windows-x86_64.msi /qn /l install.log
+--------------------------------------------
+
+Supported Windows Installer command line arguments can be viewed using:
+
+["source","sh",subs="attributes,callouts"]
+--------------------------------------------
+msiexec.exe /help
+--------------------------------------------
+
+...or by consulting the https://msdn.microsoft.com/en-us/library/windows/desktop/aa367988(v=vs.85).aspx[Windows Installer SDK Command-Line Options].
+
+[[odbc-msi-command-line-options]]
+===== Command line options
+
+All settings exposed within the GUI are also available as command line arguments (referred to as _properties_ within Windows Installer documentation) that can be passed to `msiexec.exe`:
+
+[horizontal]
+`INSTALLDIR`::
+
+  The installation directory.
+  Defaults to ++%ProgramFiles%\Elastic\ODBCDriver{backslash}{version}++.
+
+To pass a value, simply append the property name and value using the format `<PROPERTYNAME>="<VALUE>"` to
+the installation command. For example, to use a different installation directory to the default one:
+
+["source","sh",subs="attributes,callouts"]
+--------------------------------------------
+start /wait msiexec.exe /i esodbc-{version}-windows-x86_64.msi /qn INSTALLDIR="c:\CustomDirectory"
+--------------------------------------------
+
+Consult the https://msdn.microsoft.com/en-us/library/windows/desktop/aa367988(v=vs.85).aspx[Windows Installer SDK Command-Line Options]
+for additional rules related to values containing quotation marks.
+
+[[odbc-uninstall-msi-gui]]
+===== Uninstall using Add/Remove Programs
+
+The `.msi` package handles uninstallation of all directories and files added as part of installation.
+
+WARNING: Uninstallation will remove **all** contents created as part of installation.
+
+An installed program can be uninstalled by pressing the Windows key and typing `add or remove programs` to open the system settings.
+
+Once opened, find the Elasticsearch ODBC Driver installation within the list of installed applications, click and choose `Uninstall`:
+
+[[odbc-msi-installer-uninstall]]
+image::images/sql/odbc/uninstall.png[]
+
+[[odbc-uninstall-msi-command-line]]
+===== Uninstall using the command line
+
+Uninstallation can also be performed from the command line by navigating to the directory
+containing the `.msi` package and running:
+
+["source","sh",subs="attributes,callouts"]
+--------------------------------------------
+start /wait msiexec.exe /x esodbc-{version}-windows-x86_64.msi /qn
+--------------------------------------------
+
+Similar to the install process, a path for a log file for the uninstallation process can be passed using the `/l` command line argument
+
+["source","sh",subs="attributes,callouts"]
+--------------------------------------------
+start /wait msiexec.exe /x esodbc-{version}-windows-x86_64.msi /qn /l uninstall.log
+--------------------------------------------

docs/reference/sql/index.asciidoc

@@ -36,7 +36,7 @@ indices and return results in tabular format.
     SQL and print tabular results.
 <<sql-jdbc,JDBC>>::
     A JDBC driver for {es}.
-{sql-odbc}[ODBC]::
+<<sql-odbc,ODBC>>::
     An ODBC driver for {es}.
 <<sql-client-apps,Client Applications>>::
     Documentation for configuring various SQL/BI tools with {es-sql}.