The MySQL team has been continuously improving its products on the Windows platform. Along this line, we’ve responded to a request from our users of Workbench on Windows – to provide remote access to Windows Servers using Windows management methods – as an alternative to SSH.
Managing a MySQL server obviously requires access to the target machine, which usually requires elevated rights for certain tasks like restarting the server or manipulating the configuration file on Windows (where this file is in a protected path). For local connections this is mostly not a big deal. However for remote boxes security measures prevent easy manipulation of such essential things like server processes. In this blog post we discuss native Windows management and how it can be used in MySQL Workbench.
Remote Management
MySQL Workbench first introduced remote access via SSH (secure shell), a widely used and well known approach for secure remote access, especially in the Linux world. Microsoft Windows does not come with an in-built SSH server, hence an additional installation is due. For Windows users is SSH quite an unkown land and very often security rules, policies, company restrictions etc. do not allow to add extra software or open access via SSH. Also setting up SSH is non trivial and can be quite a challenge forless technical users. For these reason we have added support for native Windows management, which comes at no extra cost, since it is built into Windows already.
Native Windows Management
The management we will discuss here is not about how to add users or databases to a MySQL server and things like that. It’s rather about administering the MySQL server Instance that we’ll discuss here – for instance, DBA tasks such as manipulating the MySQL configuration file or controlling the server processes. Windows comes with a universal management layer called WMI (Windows Management Instrumentation). WMI is a very powerful means to query all kind of data from a Windows system (drivers, BIOS, motherboard, performance data etc.) and to manipulate the state of certain components (services, subsystems etc.). If you are going to manage a MySQL installation on a Windows server from a Windows machine (Workbench supports Windows 7) then WMI is the way to go. Due to security restrictions (e.g. UAC) WMI access works best in a domain setup as it already has all the necessary pieces to make the interplay work seamlessly. At the end of the article I have included additional information to help when setting up native Windows management for non-domain environments. However beware as that involves disabling some important UACs, which is not advisable in most instances.
In a Windows domain you will need is a user login that has local administrator rights on the target machine MySQL server runs on. By default firewalls and access rules are typicallu set so that Workbench can connect without extra effort. WMI is used to query a server’s status and start or stop it as well as to get system information like CPU load and memory usage. Manipulating the MySQL configuration file is done by using Window’s normal file system functions, which means the target box must provide access to the file via a shared folder. By default Windows systems have a number of default shares that are always available (so-called administrative shares that give access to the entire hard disk, provided you know the administrator’s credentials for login). On the client side you can then use different possibilities to access the server by using:
- A mapped drive, e.g. Z:\<path to file>\my.ini
- An administrative share, e.g. \\<server>\C$\<path to file>\my.ini
- An explicit share which gives access only to the file or its parent folder, e.g. \\<server>\<share>\my.ini.
This should be an old hat for most Windows users, though I wanted to point out the possibilities.
Setting up a Server Instance
Let’s get to the actual setup of a new server instance in MySQL Workbench. What you need is:
- The target server’s name or IP address.
- Name and password of a user which is a local administrator – a member of the administors group – on the target machine.
- The name of the MySQL service to manage.
- The path of the configuration file.
Workbench will try to help you with the last two points by giving you a list of MySQL servers it finds on the remote computer and their configuration file location. So it should mostly be point-and-click once you are logged in there.
Connect to the Target Machine
Open the New Server Instance Wizard from Workbench’s home screen. It comes up with the initial screen that allows you to specify the host machine of the MySQL server you want to manage thereby determining if it is a local or a remote connection. For the sake of simplicity let’s reuse a MySQL connection that has been created already in the SQL Development section. A server instance always needs such a connection. So either you reuse an already defined one or create a new one that is then added to the list of connections.
In this example I have used a Windows 2008 R2 server, which hosts the MySQL server. After selecting the connection proceed to the next page by clicking on the “Next” button. The wizard will do some initial tests and display the outcome. For a few more details (especially if something goes wrong) I recommend to open the log window using the “Show Logs” button on the wizard form.
After proceeding to the next page you will be asked to select which type of remote management you want to use. Here is where you will see the Windows Remote option.
Since we want native Windows management the option the choice is obvious. Proceeding to the next page causes the wizard to open a WMI connection to the target machine and retrieve a list of installed MySQL servers (whether running or not). Note that only the MySQL servers installed as Windows Service are recognized. In order to connect we need the credentials for a user on the target machine. As mentioned earlier, this user must be a local administrator.
Don’t get confused by the term “Service” in the login dialog. This is not the Windows service but a key that describes the given credentials. Together with the user name it defines a tupel to allow storage and retrieval of the password. Once the connection is established you can choose the server you want to manage. Selecting a server entry will automatically fill the configuration file path with a default value constructed from the server name, the administrative share C$ and the path of the file found in the service entry. Usually this is a good guess and should work most of the time.
Sometimes though things are a bit different and you can get an error when you switch to the next page.
In that case just go back to the previous page and open the file selector by clicking on the “…” button. A File Open Dialog will pop up that allows to select the file you need. This also works for remote machines, just type the machine name in the input box or use the network branch for selection. Sometimes directly accessing a share might pose problems so you may alternatively want to map a network drive in Explorer before you go on with the selection of the configuration file. For our demo the letter Z has been mapped to \\workbench.testing\C$.
After you have picked the correct file, continue to the next page which will again check if the file is accessible from MySQL Workbench. Note: only the last of the 3 tests will be performed as we already have a connection and hence don’t need to test that again. And as we are on Windows no test for any system command is required. They must be available anyway (otherwise the installation is probably broken).
Continuing, the wizard will bring up a small window asking you for a decision regarding if you just want to proceed or review what settings have been collected so far. Usually you can go on and finish the wizard after you gave your new server instance profile a proper name.
If you however want to review the details, e.g. because there is still an error at this point then click on the button “I’d like to review the settings again”. This will bring up a page that would otherwise just be skipped, which lists the collected details and allows you to opt to change them manually. This is btw. the only way to adjust the section in the configuration file that is managed by MySQL Workbench in this wizard. However, the Server Instance Manager allows to set this value as well. The default is “mysqld”.
If you checked the option “Change Parameters” you will get to a page that allows you to select the configuration file, and also let’s you test again if the file is accessible and if the given section exists in it.
Once you are satisfied with the result click “Next” to continue with the last wizard page, where you can specify a name for the new instance and finish the wizard.
Note: In the case something goes wrong you will see that the wizard does not force you to provide 100% correct details most of the time. In fact you can still continue and create the server instance even if currently no connection is possible or you do not have all relevant details. Of course without correct user credentials the wizard is not able to give you a list of installed services, so this is the minimum information, which must be correct.
What about Windows Workgroups?
In smaller and/or home networks there is typically no domain controller active, so the relationship between Windows boxes is a bit different and it is sometimes much more complicated to adjust all the necessary settings to allow this kind of access from one machine to another. Note: non-domain environments are not supported by MySQL Workbench due to various problems there.
However there are a number of web pages that discuss the use of WMI in such scenarios, which might help you to get it to work. A good overview what needs to be set can be found on the “Connecting to WMI Remotely Starting with Windows Vista” page. Most of the time you will find that these settings are already in place (except for the firewall exception), though you still get either of the most common errors:
- “RPC Server not available”, which indicates the target WMI service cannot be reached at all, usually because of firewalls or wrong server name.
- “Access denied” which is the result of access-token-filtering even if an administrator is logged in.
Denied-access errors are usually caused by the UAC. Read here what Microsoft has to say about “User Account Control and WMI”. Also consider the following tips:
- Add user with Administrator rights or set the proper rights for another user in “Computer Management/Services and Applications/WMI-Control -> context menu-> Security”
- Firewall (“netsh firewall set service RemoteAdmin enable”)
- HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\ForceGuest must be 0.
- A user connecting from a remote computer must have the SC_MANAGER_CONNECT privilege enabled to be able to enumerate services (admins usually have).
User Account Control is the major blocking stone in a workgroup environment. You will find connections to an old Windows XP box much simpler as there is no such thing as UAC there. Even for local management (i.e. MySQL Servers on the box where MySQL Workbench runs on) is affected by UAC. Running the application as administrator solves this (or disabling UAC). However since both methods are not recommended we have changed Workbench for this special case so it uses the old “sc” command to start and stop a service, in order to minimize trouble and effort for the most common case. WMI is still used for monitoring, just not for service control.
