# Configuring a DSN on Mac

> NOTE: iODBC Administrator is included with the [iODBC Driver Manager](http://www.iodbc.org/dataspace/doc/iodbc/wiki/iodbcWiki/Downloads), which must be installed in order to use the driver on Mac.

1. Open **iODBC Administrator** using the following command (this gives the application permissions to save the Driver & DSN configurations):
	1. `sudo /Applications/iODBC/iODBC\ Administrator64.app/Contents/MacOS/iODBC\ Administrator64`

## Adding a Driver Entry

Note: In order to use the OpenSearch SQL ODBC driver with the [Tableau Connector](), the **Description of the Driver** field *must* start with `OpenSearch SQL ODBC`. 

1. Go to the **ODBC Drivers** tab.
2. Click **Add a Driver**.
	* **Description of the Driver**: The driver name used for ODBC connections (ex. `OpenSearch SQL ODBC Driver`)
	* **Driver File Name**: The path to the driver file (default installed path: `/Library/ODBC/opensearch-sql-odbc/bin/libsqlodbc.dylib`)
	* **Setup File Name**: The path to the driver file (default installed path: `/Library/ODBC/opensearch-sql-odbc/bin/libsqlodbc.dylib`)
	* Set as a **System** driver
    * Below is a screenshot of how the final screen should look.
3. Click **OK** to save the options.

<p align="center"> 
<img src="img/driver_default_config.png" width="80%">
</p>

## Adding a DSN Entry

This is not required if you are using the Tableau Connector, but will help with connecting to your data source through other applications.

1. Go to the **User DSN** tab
2. Select **Add** on the right side of the window.
	* Choose the Driver you added above.
	* **Data Source Name (DSN)**: The name of the DSN used to store connection options (ex. `OpenSearch SQL ODBC DSN`)
	* **Comment**: Not required
	* Add key-value pairs by using the **'+'** button. Below is a picture of the recommended set of options for a default local OpenSearch installation.
3. Click **OK** to save the DSN configuration.

<p align="center"> 
<img src="img/dsn_default_config.png" width="80%">
</p>


## Troubleshooting

### iODBC Administrator: “General installer error” when saving new ODBC Driver

Try the following:

1. Create the folder `~/Library/ODBC`, then try again
2. Create two files in `~/Library/ODBC`, then open iODBC Administrator and verify the contents of **odbcinst.ini** and **odbc.ini** align with the format below.
	* **odbcinst.ini** (will be found in **ODBC Drivers**)
	```ini
    [ODBC Drivers]
    <Driver Name> = Installed
      
    [<Driver Name>]
    Driver = <odbc-root>/lib64/libsqlodbc.dylib
    Setup = <odbc-root>/lib64/libsqlodbc.dylib
	```
   * **odbc.ini** (will be found in **User DSNs**)
	```ini
	[ODBC Data Sources]  
    <DSN Name> = <Driver Name>
    
    [<DSN Name>]
    Driver = <odbc-root>/lib64/libsqlodbc.dylib
    Description =
    Host = localhost
    Port = 9200
    Username = admin
    Password = admin
	```

## Configuration examples

### `BASIC` Authentication

```ini
[ODBC Data Sources]
OpenSearch SQL ODBC DSN = OpenSearch SQL ODBC Driver

[ODBC]
TraceLibrary  =
Trace         = 1
TraceAutoStop = 0
TraceFile     = /Library/ODBC/opensearch-sql-odbc/odbc.log
TraceDLL      =

[OpenSearch SQL ODBC DSN]
Driver               = /Library/ODBC/opensearch-sql-odbc/bin/libsqlodbc.dylib
Host                 = https://localhost
Port                 = 9200
UseSSL               = 1
ResponseTimeout      = 6
HostnameVerification = 0
LogOutput            = /Library/ODBC/opensearch-sql-odbc
Auth                 = BASIC
```

<p align="center"> 
<img src="img/mac_dsn_config_basic_auth.png" width="80%"/>
</p>

### `AWS_SIGv4` Authentication

```ini
[ODBC Data Sources]
OpenSearch SQL ODBC DSN = OpenSearch SQL ODBC Driver

[ODBC]
TraceLibrary  =
Trace         = 1
TraceAutoStop = 0
TraceFile     = /Library/ODBC/opensearch-sql-odbc/odbc.log
TraceDLL      =

[OpenSearch SQL ODBC DSN]
Driver               = /Library/ODBC/opensearch-sql-odbc/bin/libsqlodbc.dylib
Host                 = https://search-*.us-east-1.es.amazonaws.com/
Port                 = 443
UseSSL               = 1
ResponseTimeout      = 6
HostnameVerification = 1
Region               = us-east-1
LogOutput            = /Library/ODBC/opensearch-sql-odbc
Auth                 = AWS_SIGV4
```

<p align="center"> 
<img src="img/mac_dsn_config_aws_sigv4_auth.png" width="80%"/>
</p>

### `AWS_SIGv4` Authentication with connecting to a VPC endpoint behind SSH tunnel

```ini
[ODBC Data Sources]
OpenSearch SQL ODBC DSN = OpenSearch SQL ODBC Driver

[ODBC]
TraceLibrary  =
Trace         = 1
TraceAutoStop = 0
TraceFile     = /Library/ODBC/opensearch-sql-odbc/odbc.log
TraceDLL      =

[OpenSearch SQL ODBC DSN]
Driver               = /Library/ODBC/opensearch-sql-odbc/bin/libsqlodbc.dylib
Host                 = https://localhost
Port                 = 9200
UseSSL               = 1
ResponseTimeout      = 6
HostnameVerification = 0
Region               = us-east-1
LogOutput            = /Library/ODBC/opensearch-sql-odbc
Auth                 = AWS_SIGV4
TunnelHost           = vpc-*.us-east-1.es.amazonaws.com
```

<p align="center"> 
<img src="img/mac_dsn_config_aws_sigv4_auth_with_ssh_tunnel.png" width="80%"/>
</p>