Gracefully Stopping Iguana Service on Windows

Introduction

This tip shows you how to safely shut down the Iguana service on Windows, and it also tells you what not to do. There are several ways to shut down the service, you can use the Services Manager,  the Command Prompt or the Task Manager.

Note: The screenshots on this page are from Windows 2012 R2 — the screens will vary slightly for different versions of Windows.

Task [top]

How to safely shut down the Iguana service on Windows according to our best practice.

Implementation [top]

You can shut down an Iguana service using using the Services Manager, the Task Manager or the Command Prompt (using net stop or taskill).

Using the Services Manager:

  1. Open Windows Services:

    Using the Services Manager is the “standard” way to manage Windows services.

    • Run services.msc
    • Alternatively: click Start > Control Panel > System and Security Administrative Tools > Services.
    • The Services window appears:
  2. Stop the Iguana service:
    • Choose the service to stop — in this case we will stop the iNTERFACEWARE Iguana service:
      Note: There are several Iguana servers installed on this machine.
      windows iguana service
    • Right click on the service name, click on Stop:
      right click to stop service
  3. To test that the service is stopped you can try to launch this Iguana in any browser and you will see that it is not reachable:
    Note: Be sure to use the correct port number as other Iguana services may still be running (as in this example).

Using the Command Prompt:

  1. Use the net stop command:

    Using net stop is the command line equivalent of using the Services Manager (GUI) app.

    1. Open an Command Prompt window as Administrator.
    2. Navigate to the directory where Iguana is installed
    3. Stop the service from the command line using net stop iguana:
      Note: You can also start the service using net start iguana.
      net stop iguana service
  2. Use the taskill command:
    1. Open an Command Prompt window as Administrator.
    2. To safely shut down all Iguana services running as Local Administrator:
      • Execute the following command taskkill /fi "USERNAME eq NT AUTHORITY\SYSTEM" /im iguana.exe:
        Note: This will shutdown three Iguana services as shown above in the Services Manager.
      • Alternatively you can use taskkill /pid <process id> to stop a single process identified by its PID.
    3. If and only if the service has hung (does not stop for the previous command) then you can force kill Iguana as a last resort:
      1. To force kill a process use the “/f” option for the taskkill command (equivalent of Linux/Unix kill -9)
      2. Force kill the process tree by including the “/t” option:

        This is the safest way to force a shutdown as it also kills all child processes.

        • Use taskkill /f /t /pid <process id> to kill a single process identified by its PID and all child processes.
          Taskkill /f /t
        • Alternatively you can use taskkill /f /t /fi "USERNAME eq NT AUTHORITY\SYSTEM" /im iguana.exe:
          Note: This will force the shutdown of three Iguana services as shown above in the Services Manager.
      3. Force kill only the iguana process:

        This is not recommended as it is the least safe way to stop the Iguana service

        • Execute the following command taskkill /f /pid <process id> to kill a single process identified by its PID.
        • Alternatively you can use taskkill /f /fi "USERNAME eq NT AUTHORITY\SYSTEM" /im iguana.exe:
          Note: This will force the shutdown of three Iguana services as shown above in the Services Manager.
      4. If your Iguana does not restart correctly you may need to reboot the Server to clean up Iguana memory issues caused by the forced shutdown.

Warning: Only use the “force kill” option (taskkill /f ...) as a last resort because it can result in improper shutdown. Force killing in this way is how we start running into problems with Iguana not shutting down properly.

If you do use taskkill /f ... and Iguana does not restart you may need to reboot the server (to clean up memory issues from incorrect Iguana shutdown).

Tip: If you prefer to use Windows Powershell (instead of the standard command window), then you can use the Stop-Service command which is similar to taskkill.

 

Using the Task Manager:

  1. Open the Task Manager application
  2. Right click on Service name and click End Task to stop the process:
    Note: You can also highlight the task and click the End Task button to stop the process.
    task manager - end task
  3. If and only if the service has hung (does not stop for the previous command) then you can force kill Iguana as a last resort:
    • Task Manager allows you to force stop a process tree or a just kill a process.

      These options behave in exactly the same way as the taskkill /f /t /pid <process id> (kill process tree) or the taskkill /f /pid <process id> (kill process only) ,

    • Accessing these “stop options” is different depending on which version of Windows you are using.

      We decided not to include instructions for this because Windows 7 and Windows 10 task managers behave differently. However it is fairly easy to figure out by trial and error and perhaps a little googling.

Note: If you are unable to start an Iguana service (in Services Manager), then you can check the Task Manager to see if there are any Iguana tasks running. If you find a running task then you can stop it (in Task Manager) — once the task is stopped you should be able to restart the service (in Service Manager).

Warning: Only use the “force kill” option as a last resort because it can result in improper shutdown. Force killing in this way is how we start running into problems with Iguana not shutting down properly.

If you do use the “force kill” option and Iguana does not restart you may need to reboot the server (to clean up memory issues from incorrect Iguana shutdown).

Tip: If you manage multiple versions of Windows and get annoyed by the different versions of Task Manager — then you can use the sysinternals Process Explorer (a free Microsoft utility) This provides a single (consistent) interface that works with all versions of Windows going back to Vista.

You can use it to stop or force stop Windows processes, and it provides a lot more information that Task Manager.

How it works [top]

Gracefully (safely) stopping a process:

What does this actually mean? It means that you “politely” ask the process to stop which allows it to perform cleanup before closing. This means it will wait for external processes (like web services and databases) to return results before it will shut down. Unfortunately this also means that sometimes a process will freeze or “hang” if something goes wrong, for example waiting for a database connection (or web service) that never returns a result is common cause of a frozen process.

This is the recommended way to shut down a service or process.

Force stopping a process or process tree:

What does this actually mean? It means that you “rudely” force the process to stop and do not allow it to perform cleanup before closing. This means it will not wait for external processes (like web services and databases) to return results before it shuts down. Unfortunately because cleanup is not performed it can leave various “artifacts” like, unreclaimed memory (a so called memory leak), zombie processes (child processes not shutdown), unclosed connections, etc.

This method of shutting down a service or process should only be used as a last resort for frozen (“hung”) processes.

If you do decide to stop a process you should stop the whole process tree (the process and child processes it created). Stopping the process tree is much safer than just stopping the process. However stopping the process tree is still not a clean shutdown as it prevents the process from performing cleanup processing (like waiting for external resources to return results).

Windows has many ways that you can manage processes:

  • The Services Manager (GUI) application
  • The net stop and net start command — that you run in a command window
  • The taskkill command — that you run in a command window
  • The Task Manager (GUI) application
  • The Stop-Service command — that you run in a powershell window
  • The sysinternals Process Explorer (a free Microsoft utility)

All of these methods will allow you to stop a process gracefully. Most of them (other than the first two) also allow you to force stop a process or process tree.

More information [top]

 

 

Leave A Comment?