DansGuardian Documentation Wiki

You are here: Main Index » command_line_usage


|

Wiki Information

Command Line Usage

DansGuardian usually runs as a system service (daemon), and uses the same standard method of starting, stopping, and restarting as any other system service.

Controlling System Services (including DansGuardian)

On some Linux distributions the standard method of starting and stopping services is via the command service:

  • service dansguardian start
  • service dansguardian stop
  • service dansguardian restart

On other Linux distributions the service command does not exist and system services are controlled instead with direct execution of their scripts via explicit specification of a path:

  • /etc/init.d/dansguardian start
  • /etc/init.d/dansguardian stop
  • /etc/init.d/dansguardian restart

This controlling mechanism is perfect for production use (but see the exception below). Using this same mechanism when manually controlling DansGuardian has several advantages:

  • same mechanism as used at boot
    • any problems with auto-start will be immediately obvious
    • get same effect as rebooting except much more quickly
  • problems with wrong userid are minimized
  • nothing special to remember

(Do not rely on the PATH environment variable by simply executing dansguardian without an explicit path, especially if your PATH includes dot (.) specifying the current directory. You don't know for sure what you're executing; note the control script /etc/init.d/dansguardian and the executable /sbin/dansguardian have the same name. It's very easy to actually execute something different than you intended to, and sometimes to not even realize it.)

Setting Up System Services Control

You will be able to use either service dansguardian ... or /etc/init.d/dansguardian ... on your system once DansGuardian is fully installed. But this may not happen automatically, for example if you perform your own incomplete installation process. An appropriate file should be copied from the distribution (maybe something like /usr/local/src/dansguardian-…/data/scripts/…) to /etc/init.d/dansguardian.

Starting DansGuardian Automatically At Boot

Control of which daemons (services) are started automatically at boot time is an OS function, not a DansGuardian function. In some cases the DansGuardian installation will execute the appropriate command for you, but often it won't.

The OS control of daemons is different for different systems. One common control command is update-rc.d, another is chkconfig. Both manpages and the web may provide specific guidance on how to use the appropriate command.

DansGuardian Command Line

However for debugging using the standard system service controlling mechanism may not be the best. During debugging it has some drawbacks:

  • detailed error messages are hidden, only [OK] or [Failed] are presented (and not always correctly)
  • finer control than simply Start or Stop is not possible
  • purposely launching with a different userid is more difficult

In almost all production uses, and in some debugging uses, simply use the standard method of controlling a system service. But when doing detailed debugging (or when performing the soft restart dansguardian -g, which has no analogue in standard system service control), you may need to use the DansGuardian command line directly.

(Be careful of which userid you're running as when you use the DansGuardian command line. You might accidentally launch DansGuardian under a different userid than usual, with the result that it cannot access some files [ex: config files or log files] that it usually has no problem with.)

dansguardian -h

Usage: dansguardian [{-c ConfigFileName|-v|-P|-h|-N|-q|-s|-r|-g}]
  -v gives the version number.
  -P displays the name and version of any 3rd party extensions compiled in.
  -h gives this message.
  -c allows you to specify a different configuration file location.
  -N Do not go into the background.
  -q causes DansGuardian to kill any running copy.
  -s shows the parent process PID.
  -r closes all connections and reloads config files by issuing a HUP,
     but this does not reset the maxchildren option.
  -g gently restarts by not closing all current connections and only reloads
     filter group config files by issuing a USR1.

dansguardian -r

A '-r' kills the processes to close all connection and then reloads all settings.

dansguardian -g

A '-g' gentle restart does not kill current connections but filter group config is re-read. (Note this option has no analogue in standard system services control.)

dansguardian -q

A '-q' quits dansguardian (however once in a while it does a less-than-perfect job). If you want to make absolutely sure that all DansGuardian processes are killed, first issue the dansguardian -q, then wait a few seconds, then issue the command killall dansguardian.

:!: Do not issue kill -9 dansguardian until after you've issued the regular dansguardian -q and kill dansguardian and killall dansguardian. Kill -9 is an emergency measure and should be used only after all other measures have been tried and have failed. You may be accustomed to recent operating systems that don't even present the option of nuking a process until you've first tried to end it cleanly; Linux just trusts you to issue commands in a reasonable order.