PMDAMSSQL(1)

💖 PMDAMSSQL 💖

okay bestie, welcome to pmdamssql(1) — yeah it's a section 1 General Commands Manual page, and no, we're not being boring about it 🎀

---

✨ NAME ✨

pmdamssql — the Microsoft SQL Server database PMDA, and yes she's iconic for it 💅

---

🌸 DESCRIPTION 🌸

so like, pmdamssql is a Performance Co-Pilot (PCP) Performance Metrics Domain Agent (PMDA), which is a very fancy way of saying: she pulls live performance data straight out of a running Microsoft SQL Server database server. real-time tea, no cap ✨

---

🎀 CONFIGURATION 🎀

first things first, bestie — pmdamssql needs some support packages installed before she can do her thing:

• mssql-server — the main character 💜 the primary Microsoft SQL Server database package.
• msodbcsql18, msodbcsql17 or msodbcsql — the Microsoft SQL Server ODBC bindings. pick your fighter, any of these three works.
• pyodbc — the general Python ODBC module, with Microsoft SQL Server support enabled. she needs that switch flipped, fr fr.

---

next up, pmdamssql reads an optional ini-style configuration file:

$PCP_PMDAS_DIR/mssql/mssql.conf

this file currently has room for two sections — one for configuring the library that connects to SQL server, and the other for authenticating with SQL server. two little rooms, two little vibes 🦋

[connection] section 🫶

this one specifies values for the following settings (their default values are shown in parenthesis, iykyk):

• driver ({ODBC Driver 17 for SQL Server}) — the ODBC driver string.
• server (tcp:localhost) — the SQL Server socket connection string.
• timeout (2) — the connection timeout setting, in seconds.

[authentication] section 🔥

this section specifies values for the two supported modes of authentication with SQL Server.

mode one: SQL Server authentication (the default)

the default is to use SQL Server authentication, which requires a username and password to be provided. these are the configuration settings (defaults in parenthesis, as always bestie):

• 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 line contains the username, and the second line contains the password. simple, clean, iconic.

mode two: Windows authentication mode

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 — go read her, she's important 🧚).

---

💅 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

okay so important: pmdamssql is launched by pmcd(1) and should never be executed directly. she does not take walk-ins, she gets booked 💀 the Install and Remove scripts notify pmcd(1) when the agent is installed or removed, so everything stays in the loop.

also good news: pmdamssql will automatically attempt to reconnect to the SQL Server if its connection is lost — e.g. if the SQL Server service is restarted. resilient queen 👑

---

⭐ 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, so don't come for her if your paths are different bestie 🌈

---

🌈 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). periodt 💜

---

👑 SEE ALSO 👑

PCPIntro(1), kinit(1) and pmcd(1). go give them a read, they're all slay in their own way 🫶

---

and that's the whole page bestie!! this was Performance Co-Pilot, PCP, PMDAMSSQL(1) — thanks for reading, ily, now go monitor some databases 💖✨🎀🦋