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 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.

    1. Enter “services” into Windows Search and run the Services App:

      This works on Windows 10 and Windows 7. Alternatively you can run services.msc.

      search for services

    2. The Services window appears:
      services window
  2. Stop the Iguana service:
    1. Choose the service to stop — in this case we will stop the iNTERFACEWARE Iguana service:
    2. Right click on the service name, click on Stop:

      The Status column changes from Running to blank.

      blank status

  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: 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).

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.

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 a 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:
      You can also start the service using net start iguana.

      net stop start

  2. Use the taskill command:
    1. Open a 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_service.exe:

        This command will shut down all the Iguana services that are running using the specified user name.

      • Alternatively you can use taskkill /pid <process id> to stop a single iguana_service.exe 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_service.exe as a last resort:

      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 force kill and Iguana does not restart you may need to reboot the server (to clean up memory issues from incorrect Iguana shutdown).

      1. To force kill a process use the “/f” option for the taskkill command (equivalent of Linux/Mac 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.

        1. Use taskkill /f /t /pid <process id> to kill a single process identified by its PID and all child processes:
          taskill iguana_service
        2. Alternatively you can use taskkill /f /t /fi "USERNAME eq NT AUTHORITY\SYSTEM" /im iguana.exe:

          This command will force a shut down all the Iguana services that are running using the specified user name.

      3. Force kill only the iguana process:

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

        1. Execute the following command taskkill /f /pid <process id> to kill a single iguana.exe process identified by its PID.
        2. Alternatively you can use taskkill /f /fi "USERNAME eq NT AUTHORITY\SYSTEM" /im iguana.exe:

          This command will force a shut down all the Iguana services that are running using the specified user name.

          force taskill iguana.exe

        3. 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.

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:

    You can also highlight the task and or click the End Task button to stop the process.

    end task

  3. If and only if the service has hung (does not stop for the previous command) then you can force kill Iguana (see the previous section).

    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).

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?