# pmdamssql

## NAME



           **pmdamssql** - Microsoft SQL Server database PMDA
    


## DESCRIPTION



           **pmdamssql** is a Performance Co-Pilot (PCP) Performance Metrics
           Domain Agent (PMDA) which extracts live performance data from a
           running Microsoft SQL Server database server.
    


## CONFIGURATION



           Firstly, **pmdamssql** requires installation of these support
           packages:
    
           **mssql-server**
                The primary Microsoft SQL Server database package.
    
           **msodbcsql18** , **msodbcsql17** or **msodbcsql**
                Microsoft SQL Server ODBC bindings.
    
           **pyodbc**
                General Python ODBC module with Microsoft SQL Server support
                enabled.
    
           Next, **pmdamssql** reads an optional ini-style configuration file:
    
                  $PCP_PMDAS_DIR _/mssql/mssql.conf_
    
           This file currently allows for two sections, one for configuring
           the library that connects to SQL server, the other for
           authenticating with SQL server.
    
           **[connection]** section specifies values for the following settings
           (their default values are shown in parenthesis):
    
           **driver**(_{ODBC Driver 17 for SQL Server}_)
                  ODBC driver string.
    
           **server**(_tcp:localhost_)
                  SQL Server socket connection string.
    
           **timeout**(_2_)
                  Connection timeout setting, in seconds.
    
           **[authentication]** section specifies values for the two supported
           modes of authentication with SQL Server.
    
           The default is to use SQL Server authentication, which requires a
           username and password to be provided.  These are the following
           configuration settings (their default values are shown in
           parenthesis):
    
           **username**(_pcp_)
                  Username to connect to the database.
    
           **password**(empty)
                  Password to connect to the database.
    
           Note that if a SQL Server Assessments API configuration file is
           found at _/var/opt/mssql/secrets/assessment_ , then **pmdamssql** reads
           the username and password from that file preferentially.  The
           format is simply a two line text file, the first containing the
           username and the second the password.
    
           The second option is Windows authentication mode, where logins are
           created in SQL Server that are not based on operating system user
           accounts.
    
           **trusted**(_false_)
                  Set to _true_ to use Windows authentication when connecting
                  to the database.
    
           This is a Kerberos-style connection and credentials must be
           available before the PMDA is started (see **kinit**(1) for further
           details).
    


## INSTALLATION



           To install, the following must be done as root:
    
               **# cd $PCP_PMDAS_DIR/mssql**
               **# ./Install**
    
           To uninstall, the following must be done as root:
    
               **# cd $PCP_PMDAS_DIR/mssql**
               **# ./Remove**
    
           **pmdamssql** is launched by pmcd(1) and should never be executed
           directly.  The **Install** and **Remove** scripts notify pmcd(1) when the
           agent is installed or removed.
    
           **pmdamssql** will automatically attempt to reconnect to the SQL
           Server if its connection is lost - e.g. if the SQL Server service
           is restarted.
    


## FILES



           $PCP_PMDAS_DIR _/mssql/mssql.conf_
                configuration file for the **pmdamssql** agent
    
           $PCP_PMDAS_DIR _/mssql/Install_
                installation script for the **pmdamssql** agent
    
           $PCP_PMDAS_DIR _/mssql/Remove_
                undo installation script for the **pmdamssql** agent
    
           $PCP_LOG_DIR _/pmcd/mssql.log_
                default log file for messages from the **pmdamssql** agent
    
           Note that the usual/default value for **$PCP_PMDAS_DIR** is
           **/var/lib/pcp/pmdas** and the default for **$PCP_LOG_DIR** is
           **/var/log/pcp** but these settings are platform dependent.
    


## PCP ENVIRONMENT



           Environment variables with the prefix **PCP_** are used to
           parameterize the file and directory names used by PCP.  On each
           installation, the file _/etc/pcp.conf_ contains the local values for
           these variables.  The **$PCP_CONF** variable may be used to specify an
           alternative configuration file, as described in pcp.conf(5).
    


* * *