General

A. 1.0

What is DenyHosts?

Additionally, upon discovering a repeated attack host, the /etc/hosts.deny file is updated to prevent future break-in attempts from that host.

An email report can be sent to a system admin.

Return to top

A. 1.1

Who should use DenyHosts?

A. 1.2

Who wrote DenyHosts?

A. 1.3

What steps can I take to make sshd more secure?

1. Disable logins to root. This can be accomplished by setting the PermitRootLogin setting in the sshd_config file (typically, /etc/ssh/sshd_config).
   PermitRootLogin no

2. Disable password logins entirely by editing the PasswordAuthentication setting. By doing so, each user with access to the server will need to create ssh keys (which is beyond the scope of this document).
   PasswordAuthentication no

3. Run sshd on a different port. By default, sshd runs on port 22. Most sshd hackers will only attack port 22 so if you run sshd on a different port, the chances of being compromised are reduced dramatically. However, by running sshd on an alternate port requires each user to be aware of this (so if your server is accessed by many user accounts then this solution might not be feasible). To run sshd on an alternate port simply edit the sshd_config and set the Port setting appropriately:
   Port 9922

   To access yourserver running on port 9922 you would connect using the -p command line option:
   $ ssh -p 9922 yourserver

   Alternatively, you can edit your $HOME/.ssh/config file or your site-wide /etc/ssh/ssh_config file and add an entry similar to:

   Host yourserver

   Port 9922

4. Install DenyHosts!

A. 1.4

What was the motivation behind DenyHosts?

A. 1.5

How does DenyHosts work?

DenyHosts then processes the sshd server log (typically, this is /var/log/secure, /var/log/auth.log, etc) and determines which hosts have unsuccessfully attempted to gain access to the ssh server. Additionally, it notes the user and whether or not that user is root, otherwise valid (eg. has a system account) or invalid (eg. does not have a system account).

When DenyHosts determines that a given host has attempted to login using a non-existent user account a configurable number of attempts (this is known as the DENY_THRESHOLD_INVALID), DenyHosts will add that host to the /etc/hosts.deny file. This will prevent that host from contacting your sshd server again.

The DENY_THRESHOLD_ROOT configuration value specifies the maximum acceptable times that the root user account can fail to login before being blocked. Typically this value is set lower than DENY_THRESHOLD_INVALID such that root level attackers are blocked earlier than other accounts. It is also a good practice to disable root logins within the sshd.conf file in conjunction with this setting. By doing so, no user can login to root@your-server and their host will be blocked from attacking other user accounts when the DENY_THRESHOLD_ROOT is reached.

The DENY_THRESHOLD_VALID configuration value specifies the maximum acceptable times a valid user (ie. a user that exists in /etc/passwd) can fail to login before being blocked. This parameter can be helpful for those with "fat fingers". Typically this value is set higher than DENY_THRESHOLD_INVALID.

Also, DenyHosts will note any successful logins that occurred by a host that has exceeded the deny_threshold. These are known as suspicious logins and should be investigated further by the system admin.

Return to top

A. 1.6

What else does DenyHosts do?

A. 1.7

What are the requirements for running DenyHosts?

A. 1.8

I just installed DenyHosts and receive a SyntaxError: invalid syntax. What happened?

File "/etc/init.d/denyhosts", line 72  
   if args: cmd+= ' '.join(args)
                ^
 SyntaxError: invalid syntax

Then you are using an earlier version of Python. DenyHosts requires Python v2.3 or later.

Return to top

A. 1.9

My server has an earlier version of Python installed, can I still run DenyHosts?

If you downloaded version Python v2.3, then the executable is python2.3. If you downloaded Python v2.4 then the executable is python2.4.

If you will be using DenyHosts in daemon mode, then you will need to edit the daemon-control-dist script. You will want to copy this file to "daemon-control" such that future DenyHosts upgrades will preserve your edits.

$ cp daemon-control-dist daemon-control

Assuming you installed Python v2.4 and the executable is in /usr/bin then you will need to make the following changes to your daemon-control script:

Line #	From	To
1	#!/usr/bin/env python	#!/usr/bin/python2.4
18	PYTHON_BIN = "/usr/bin/env python"	PYTHON_BIN = "/usr/bin/python2.4"

You may need to modify the above paths to reflect the actual installation location and version of Python that you installed.

If you are not using DenyHosts in daemon mode then to execute DenyHosts you would do the following:

$ python2.4 denyhosts ... args...

-or-

A. 1.10

Will DenyHosts work with my sshd configuration?

A. 1.11

This FAQ is cool... I want one! How did you create it?

A. 1.12

The DenyHosts logo is cool, who designed it?

A. 1.13

Where can I download DenyHosts from?

DenyHosts is currently released in several formats by the author:

• Source tar.gz
• An RPM for Python 2.3
• An RPM for Python 2.4
• Source RPM

Additionally, DenyHosts has been re-packaged and/or is available for the following distributions:

• Fedora Core
• Redhat
• Debian
• Gentoo
• Solaris
• FreeBSD
• Mac OS/X

A. 1.14

Is DenyHosts available as a Redhat or Fedora Core package?

Additionally, DenyHosts is included in the Fedora Extras repository repository and should be accessible via yum and/or up2date. You can view the appropriate repository:

Fedora Core 4
Fedora Core 3

Return to top

A. 1.15

Is DenyHosts available as a Debian package?

Falko Timme has written a "How To" document on How to setup DenyHosts on Debian

Return to top

A. 1.16

Is DenyHosts available for Mac OS/X?

If you are using Mac OS v10.4 or greater

If you are using Mac OS v10.3 or earlier

Return to top

A. 1.17

Is DenyHosts available for Gentoo?

# Install DenyHosts
emerge --ask denyhosts

# Configure
$EDITOR /etc/denyhosts.conf

# Add to default runlevel (so that the daemon runs automatically at boot)
rc-update add denyhosts default

# Lauch daemon
/etc/init.d/denyhosts start

Return to top

A. 1.18

DenyHosts is cool, can I make a generous donation?

Portions of your donation help support SourceForge and the Python Software Foundation (and PayPal takes a piece too). Whatever money remains will no doubt be spent on delicious beer and other less important necessities of life.

Return to top

A. 1.19

Are there other tools similar to DenyHosts?

• Fail2Ban
• BlockHosts
• Blacklist

Configuring DenyHosts

A. 2.0

How do I configure DenyHosts?

A. 2.1

How do I configure cron for DenyHosts use?

# crontab -e

The above command will launch the crontab editor. To launch DenyHosts every 20 minutes you would then add the following line to the crontab:

0,20,40 * * * * python PATH_TO_DENYHOSTS/denyhosts.py -c PATH_TO_DENYHOSTS_CONFIG/denyhosts.cfg

You will need to substitute your site-specific paths above. As an example, if you installed DenyHosts in /usr/local/etc and maintain your configuration file there as well, then the following crontab entry would be appropriate:

0,20,40 * * * * python /usr/local/etc/denyhosts/denyhosts.py -c /usr/local/etc/denyhosts/denyhosts.cfg

Once you have edited the crontab you should then save it. Assuming you didn't make any errors, the crontab will automatically install itself.

For more information regarding the crontab format please see the crontab man page (man 5 crontab).

Return to top

A. 2.2

How can I disable hostname lookups?

A. 2.3

Will DenyHosts work with metalog?

Based on a patch contributed by Mike Kelly, DenyHosts 0.7 and greater will successfully parse syslog and metalog log formats. This feature is implemented in a seemless manner so there is no further configuration necessary in order to use DenyHosts with metalog.

Return to top

A. 2.4

Will DenyHosts work with FreeBSD?

You may also wish to view these items:

• this FAQ answer
• article written by Francesa Smith that provides more information.

A. 2.5

Will DenyHosts works with Solaris?

A. 2.6

Can I use a non-standard hosts.deny file?

1. edit your HOSTS_DENY configuration value to point it to another file such as "/etc/hosts.evil".
2. edit your BLOCK_SERVICE configuration value and leave it blank
3. edit your /etc/hosts.allow file and add:

   sshd: ALL EXCEPT /etc/hosts.evil

4. issue the following command:
   touch /etc/hosts.evil

This procedure will only work on DenyHosts 0.7 and greater and was implemented based on a patch contributed by John Meinel Jr.

Return to top

A. 2.7

Can I use DenyHosts on FreeBSD using a non-standard hosts.deny file?

1. edit your HOSTS_DENY configuration value to point it to another file such as "/etc/hosts.evil".
2. edit your BLOCK_SERVICE configuration value and leave it blank
3. edit your /etc/hosts.allow file and add:

   sshd : /etc/hosts.evil : deny
   sshd : ALL : allow

4. issue the following command:
   touch /etc/hosts.evil

A. 2.8

Can DenyHosts purge old entries added to the HOSTS_DENY file?

$ denyhosts.py --purge

When DenyHosts is run with the --purge flag it locates entries in the HOSTS_DENY file that have been previously timestamped by DenyHosts that have exceeed the PURGE_DENY value using the following algorithm:

1. HOSTS_DENY is backed up to a file named HOSTS_DENY.purge.bak
2. a temp file is created, HOSTS_DENY.purge.tmp
3. the HOSTS_DENY is parsed and each non-expired entry and each non-timestamped entry will be written to HOSTS_DENY.purge.tmp
4. each HOSTS_DENY that has expired (based on PURGE_DENY) will not be written to HOSTS_DENY.purge.tmp
5. after all lines are parsed, if atleast one entry was not written to HOSTS_DENY.purge.tmp (that is, no entries were expired) then HOSTS_DENY.purge.tmp will be deleted and no further processing will be performed.
6. otherwise, HOSTS_DENY.purge.tmp is moved to HOSTS_DENY (atomically-- such that even in the case of failure, the HOSTS_DENY should always be present). In the event of a catastrophic emergency you can manually move the HOSTS_DENY.purge.bak back to HOSTS_DENY.

The PURGE_DENY value is given as a time specification.

• PURGE_DENY = # an empty value disables the purge facility
• PURGE_DENY = 1h # purge entries older than one hour
• PURGE_DENY = 20m # purge entries older than twenty minutes
• PURGE_DENY = 31d # purge entries older than 31 days
• PURGE_DENY = 2w # purge entries older than two weeks
• PURGE_DENY = 1y # purge entries older than one year

Entries in HOSTS_DENY that were added before the PURGE_DENY value was defined (for example, if you upgraded from a previous version of DenyHosts or you have just decided to enable the purge functionality) will not be impacted by the --purge flag. However, if you wish for these "legacy" HOSTS_DENY entries to be subject to expiration then you will need to migrate your HOSTS_DENY data.

Once PURGE_DENY has been configured to a non-empty value, DenyHosts will automatically timestamp each record that is added to HOSTS_DENY. If PURGE_DENY is empty then DenyHosts will not timestamp the records added to HOSTS_DENY.

Return to top

A. 2.9

What time values are appropriate for PURGE_DENY, DAEMON_SLEEP, DAEMON_PURGE?

number[period] Where number is any integer greater than zero and period can contain one of the values in: s, m, h, d, w, y. Where:

• s: seconds
• m: minutes
• h: hours
• d: days
• w: weeks
• y: years

If the period is blank, then seconds is assumed.

Examples:

• 1d is one day
• 10 is 10 seconds
• 10s is 10 seconds
• 3w is 3 weeks
• 30m is 30 minutes
• 120d is 120 days

A. 2.10

I just upgraded to 1.0.0, what do I need to do?

DenyHosts 1.0.0 adds two additional required configuration parameters that must be defined. You can refer to the denyhosts.cfg-dist file for sample usage of the new DENY_THRESHOLD_ROOT and DENY_THRESHOLD_VALID parameters. These parameters are also documented.

Return to top

A. 2.11

I just upgraded to 0.9.9 (or later) what do I need to do?

To upgrade your HOSTS_DENY file to the new timestamped format you must first invoke denyhosts with the --upgrade099 flag.

$ denyhosts.py --upgrade099

Versions between 0.8.0 and 0.9.8 added a comment-timestamp (when PURGE_DENY was set) that caused tcp_wrappers to report an error. DenyHosts 0.9.9 fixes this problem by upgrading the entries of HOSTS_DENY to an alternative format which should prevent errors from being reported.

If you are upgrading from a version prior to 0.8.0 or have not yet set PURGE_DENY then there is no need to upgrade. If you wish to now set PURGE_DENY for the first time then you should run DenyHosts with the --migrate flag rather than the --upgrade099 flag.

Return to top

A. 2.12

DenyHosts is unable to parse my syslog (or other) log file

The following regex entries can be overridden in your denyhosts.cfg file:

• SSHD_FORMAT_REGEX
• FAILED_ENTRY_REGEX
• FAILED_ENTRY_REGEX2
• FAILED_ENTRY_REGEX3
• FAILED_ENTRY_REGEX4
• FAILED_ENTRY_REGEX5
• FAILED_ENTRY_REGEX6
• SUCCESSFUL_ENTRY_REGEX

Note that each of these configuration parameters are completely optional. If a value is not configured within this file then the default value will be used. The defaults can be seen by viewing the DenyHosts/regex.py file within the source distribution.

When providing a custom regular expression make sure that you only include the portions between the opening and closing triple-quotes (ie. '''this value'''). That is, if you are modifying the SSHD_FORMAT_REGEX which appears in DenyHosts/regex.py as:

SSHD_FORMAT_REGEX = re.compile(r""".* (sshd.*:|\[sshd\]) (?P<message>.*)""")

You would enter the following in your denyhosts.cfg file:

SSHD_FORMAT_REGEX = .* (sshd.*:|\[sshd\]) (?P<message>.*)

You could then customize the above regex as you see fit based on your log file's particular format. You can use a tool such as Kodos (also developed by Phil Schwartz) to test your custom regex patterns against your log contents.

If I do provide you with a custom regex that helps DenyHosts perform for your particular configuration, please consider making a donation.

Return to top

A. 2.13

Can I supply additional regular expressions to DenyHosts?

Examples:

USERDEF_FAILED_ENTRY_REGEX=break in attempt for (?P.*) from (?P.*)
USERDEF_FAILED_ENTRY_REGEX=break in attempt from (?P.*)

If multiple USERDEF_FAILED_ENTRY_REGEX are supplied they are evaluated in the order that they appear in the configuration file. Additionally, this parameter is evaluated after the built-in regular expressions (ie. FAILED_ENTRY_REGEX, FAILED_ENTRY_REGEX2, ...).

Return to top

A. 2.14

What is the difference between FAILED_ENTRY_REGEX and USERDEF_FAILED_ENTRY_REGEX?

The optional USERDEF_FAILED_ENTRY_REGEX configuration parameter can be specified in order to add additional regular expressions to DenyHosts which may allow it to identify more hacker attempts based on your particular configuration. Therefore, these regular expressions do not replace the non-USERDEF versions and are intended to extend DenyHosts hacker recognition.

Return to top

A. 2.15

Can I use DenyHosts with djb multilog?

@4000000042f4e1d3057febbc Failed password for invalid user network ...
@4000000042f4e1d305800ee4 Connection closed by ...

In order for DenyHosts to easily parse this log format, simply edit your denyhosts.cfg file and add the following line:

SSHD_FORMAT_REGEX = @.*? (?P<message>.*)

Return to top

A. 2.16

Why isn't DenyHosts recognizing successful ssh logins?

For instance, if your log file has the following entry:

error: PAM: authentication error for SOME_VALID_USERNAME from 192.168.1.1

A. 2.17

What is the difference between DENY_THRESHOLD_INVALID, DENY_THRESHOLD_ROOT and DENY_THRESHOLD_VALID and DENY_THRESHOLD_RESTRICTED?

DENY_THRESHOLD_ROOT - applies to login attempts to the root user account

DENY_THRESHOLD_VALID - applies to existent user accounts (those that exist within /etc/passwd)

DENY_THRESHOLD_RESTRICTED - (New in v2.1) Applies to the optionally defined usernames in WORK_DIR/restricted-usernames. See restricted users for more details.

Typically, the value for DENY_THRESHOLD_VALID should be larger than the DENY_THRESHOLD_INVALID value and the value for DENY_THRESHOLD_ROOT should be less than DENY_THRESHOLD_INVALID. That is:
DENY_THRESHOLD_ROOT < DENY_THRESHOLD_INVALID < DENY_THRESHOLD_VALID

DENY_THRESHOLD_RESTRICTED should typically be the same as DENY_THRESHOLD_ROOT.

As an example, consider a system "myhost" that has a valid user "foo" and an invalid user "bar" (that is, "foo" exists in the /etc/passwd file on "myhost", whereas "bar" does not). If a user at host 1.1.1.1 attempts to login to "foo@myhost" more than DENY_THRESHOLD_VALID then 1.1.1.1 will be blocked (added to the HOSTS_DENY file). However, if a user at 2.2.2.2 had attempted to login to "bar@myhost" then that IP address would be blocked after DENY_THRESHOLD_INVALID attempts. If a user at 3.3.3.3 attempted to login to multiple accounts ("foo" and "bar") then the IP address would be blocked as soon as either threshold was exceeded.

Therefore, at most, a malicious user can attempt to gain access to your system DENY_THRESHOLD_INVALID + DENY_THRESHOLD_VALID times before being added to HOSTS_DENY.

Return to top

A. 2.18

Can I specify a set of users that should never be able to login?

• An account that does not allow logins (such as lpd)
• An account that should never login via ssh (such as mysql)
• A ficticious username that often is associated with hackers (such as toor)

Any username listed in the restricted-usernames file will be subject to the DENY_THRESHOLD_RESTRICTED configuration setting (by default this will be set to DENY_THRESHOLD_ROOT).

To aid in creating a suitable restricted-usernames file there are currently 2 scripts in the scripts subdirectory:

• restricted_from_passwd.py will parse the /etc/passwd file, find each of the usernames that have /sbin/nologin, /sbin/halt or /sbin/shutdown shells and output them to the console. You can either cut-and-paste these into restricted-usernames or redirect the output to this file.
• restricted_from_invalid.py will parse DenyHosts invalid login attempts file and find the most frequently attacked user accounts on your system. You must provide your WORK_DIR setting on the command line so that this script can locate the necessary file to parse, namely users-invalid. You can also specify the number of usernames to display, the default is 10.

Note: This restricted-usernames file is loaded at start-up time so any changes you make while the DenyHosts daemon is still running will not take effect until you restart the daemon.

Return to top

A. 2.19

Can I specify an alternate timestamp format for the DAEMON_LOG file?

By default, DenyHosts (when run in daemon mode) will timestamp log entries with an ISO8061 timestamp format. This may be undesirable for some users and may not blend easily with 3rd party packages such as log_check, log_watch, etc). To specify an alternate timestamp format, simply set the DAEMON_LOG_TIME_FORMAT parameter in the denyhosts.cfg file. It is recommended that you refer to the man page for strftime for possible values.

A typical alternative timestamp may be Jan 1 22:05:59. To set the DAEMON_LOG_TIME_FORMAT to this format, insert the following line in your denyhosts.cfg file:

DAEMON_LOG_TIME_FORMAT = %b %d %H:%M:%S

Return to top

A. 2.20

Can failed login attempts be reset over a period of time?

The AGE_RESET_* parameters are optional. If not provided, failed login attempts per host will not be reset automatically (this is the behavior in previous versions of DenyHosts). The following parameters can be specified in the DenyHosts configuration file:

• AGE_RESET_VALID - applies to login attempts to existant users (those that appear in /etc/passwd) with the exception of the root user
• AGE_RESET_ROOT - applies to the root user account
• AGE_RESET_INVALID - applies to non-existant users (those that do not appear in /etc/passwd)
• AGE_RESET_RESTRICTED - (new in 2.1) applies to usernames that are optionally defined in WORK_DIR/restricted-usernames (typically, usernames that appear in /etc/passwd that should not be able to login, such as "lpd" or "apache")

Return to top

A. 2.21

Can failed login attempts be reset automatically?

A. 2.22

Does DenyHosts support plugins?

Two optional configuration parameters exist to support plugins. They are:

• PLUGIN_DENY - specifies the program to be run when a host is blocked by DenyHosts
• PLUGIN_PURGE - specifies the program to be run when a host is no longer blocked by DenyHosts

Each of the executed programs will receive the host (typically the IP address) that was denied/purged as it's sole argument.

Return to top

A. 2.23

Can TCPWRAPPERS automatically invoke DenyHosts per login attempt?

A. 2.24

Can I dynamically specify configuration values?

To specify a dynamically substituted value you specify the portion of the value you would like to replace using the syntax $[ ... ] where the ... maps to an environment variable name.

Notes: the environment variable must be specified in UPPERCASE and will be retrieved from the local environment when DenyHosts is started. Therefor, if you make a change to the underlying environment variable that you would like DenyHosts to use then you must restart DenyHosts.

You may wish to do this, for instance, if you run DenyHosts on several servers and would like to use the same configuration file on each. In this case, you may want to dynamically specify the server name for the SMTP_SUBJECT option.

SMTP_SUBJECT = DenyHosts report - $[HOSTNAME]

If the systems HOSTNAME environment variable is defined as foo.bar.com then the SMTP_SUBJECT will be interpreted as:

SMTP_SUBJECT = DenyHosts report - foo.bar.com

All DenyHosts configuration values can be specified to include environment variables in this way.

Return to top

A. 2.25

How can I rotate the DenyHosts logfile (/var/log/denyhosts)?

# how many historical logs do you wish to keep
rotate 5

# don't rotate empty logs
notifempty

missingok

# uncomment this if you want the file created with
# rw permissions for the root user and root group
#create 0600 root root

# uncomment this if you want to compress the rotated files
#compress

# uncomment this out if you want to rotate it each day
#daily

# uncomment this out if you want to rotate it each month
#monthly

# uncomment this if you want the logs to be capped at a
# certain size and then specify the size. 
#size=64k

# this should match the DAEMON_LOG configuration setting of DenyHosts
/var/log/denyhosts {
        prerotate
                service denyhosts stop
        endscript
        postrotate
                service denyhosts start
        endscript
}

Using DenyHosts

A. 3.0

I've configured DenyHosts, now what?

This can be done by invoking DenyHosts with the --file= flag:
$ python denyhosts.py --file=/var/log/secure.log.1

Additionally, you can process several files at once:
$ python denyhosts.py --file=/var/log/secure.log.1 --file=/var/log/secure.log.2 .... --file=/var/log/secure.n

Note: You must run DenyHosts as root so that it can read /var/log/ files and update the /etc/hosts.deny file

Return to top

A. 3.1

Do I need to run DenyHosts as root?

In all other cases, such as running DenyHosts from cron then technically speaking, no. However, in order to run DenyHosts as non-root you must ensure that you have read-permissions on the /var/log/ sshd server logs. Alternatively, you can copy them to a directory where you do have read-permissions.

Also, in order for DenyHosts to block hosts, it needs write permissions for the /etc/hosts.deny file. DenyHosts will gladly run without being able to update this file. In this mode, the hosts that should be blocked are written to stdout (in a form suitable for pasting into /etc/hosts.deny). Also, you can use an alternate HOSTS_DENY file (other than /etc/hosts.deny) which may not require root priviledges.

Return to top

A. 3.2

How should DenyHosts be run?

In addition to the deamon mode, DenyHosts can also be run periodically from the command line. If you do not wish to use the daemon mode, then I recommend that DenyHosts be run from cron on a routine basis. DenyHosts is fairly lightweight and does not put an excessive drain on system resources. DenyHosts initially checks to see if the sshd log has changed in size and if it determines that it hasn't, then it exits without further processing. If the log has changed, DenyHosts only examines the portion that has changed.

The interval between DenyHosts runs is left up to the user. Personally, I run DenyHosts every 10 minutes.

Return to top

A. 3.3

When my logs are rotated will DenyHosts work properly?

• If the first line is different, then DenyHosts will process the entire log file (since it is assumed that the log has been rotated).
• If the first line is the same it then compares the file size to the last runs offset.
  • If they are the same, then DenyHosts assumes that there are no changes and exits.
  • If the current file size is greater then the last offset, then the log file is processed from the last offset.
• When DenyHosts exits it stores the first line of the processed log file and the file offset into the offset file (which is located in the WORK_DIR that is defined in your denyhosts.cfg file).

A. 3.4

I want to process the entire log file regardless of the last offset, how can I do this?

A. 3.5

DenyHosts exits without producing any output, what happened?

However, if you'd like to see more details of what it's doing, you can supply the --verbose flag on the command line.

Alternatively, if you'd like to see all of the gory details of what DenyHosts is doing, you can invoke DenyHosts with the --debug flag. It is recommened, when reporting a bug that you supply the output from running DenyHosts with the --debug flag.

Return to top

A. 3.6

I don't want to receive an email report of hosts added to /etc/hosts.deny.

Seriously, though, if you would like to disable the email reports you can either edit the denyhosts.cfg file (and set the admin_email value to nothing) or run the script with the --noemail flag supplied.

# in your denyhosts.cfg file:
ADMIN_EMAIL=

# command line:
$ python denyhosts.py --noemail

Return to top

A. 3.7

How can I prevent a legitimate IP address from being blocked by DenyHosts?

Additionally, as of v1.0.3, a valid hostname can also be placed in the allowed-hosts file. For each hostname appearing in this file, the IP address will be resolved and any ssh connections that match either this hostname or this resolved IP address will not be blocked. # this is a comment line
# the following line prevents DenyHosts from blocking IP address 1.1.1.1
1.1.1.1
# The following lines prevent IP addresses 1.1.1.2 and 1.1.1.3 from being blocked
1.1.1.2
1.1.1.3
#
# The first 3 parts of the IP address must be provided (eg. 1.2.3.)
# The last part of the IP address can be a wildcard.
# The wildcard can be given with an asterisk -or- as a range.
#
# This line prevents all IP address in the 1.1.1 network from being blocked
# 1.1.1.*
#
# This line prevents IP addresses in the range 1.1.1.6 to 1.1.1.23 from being blocked
# 1.1.1.[6-23]
# the following line prevents DenyHosts from blocking the host foo
foo

Return to top

A. 3.8

What if SSH sometimes logs hostnames rather than IP addresses
How can I prevent these from being blocked?

To enable this feature, you must specify the following option in your configuration file:

ALLOWED_HOSTS_HOSTNAME_LOOKUP=yes

Note: Depending on the number of entries in your allowed-hosts file, this operation can be network intensive but only at DenyHosts startup. Therefor, It is recommended that this option only be used when running DenyHosts in daemon mode since this initialization only occurs once. Additionally, if hostnames never appear in your SECURE_LOG then you shouldn't set this parameter at all (or set it to no):

ALLOWED_HOSTS_HOSTNAME_LOOKUP=no

Return to top

A. 3.9

DenyHosts reports suspicious login activity for allowed hosts, how can I stop this?

This parameter can be set to YES or NO. The default value is YES. If you wish to change the default behavior and only report suspicious login activity from unknown ip addresses, set this value to NO.

Regardless of whether this value is YES or NO, if the suspicious login did not originate from a known allowed-hosts the activity will always be reported. That is, this parameter only applies to ip addresses in your allowed-hosts file.

Return to top

A. 3.10

Can DenyHosts process gzipped logfiles

$ denyhosts.py -f /var/log/secure.log.1.gz

When DenyHosts encounters a gzipped logfile it will automatically open it (without uncompressing it on disk) and process it.

Return to top

A. 3.11

Can DenyHosts process bzipped (bz2) logfiles

$ denyhosts.py -f /var/log/secure.log.1.bz2

When DenyHosts encounters a bzipped logfile it will automatically open it (without uncompressing it on disk) and process it.

Return to top

A. 3.12

I've just upgraded to 0.8.0 (or greater) and want to update my HOSTS_DENY for use with PURGE_DENY

To instruct DenyHosts to migrate your HOSTS_DENY for use with PURGE_DENY invoke DenyHosts with the --migrate flag:

$ denyhosts.py --migrate

Note:
Using the --migrate flag without previously defining a value for the PURGE_DENY parameter will result in an error condition such that DenyHosts will exit immediately.

When DenyHosts is run with the --migrate flag it locates entries in the HOSTS_DENY file that have not been been previously timestamped by DenyHosts and timestamps them (using the current time). The following algorithm is used to update the HOSTS_DENY file:

1. HOSTS_DENY is backed up to a file named HOSTS_DENY.migrate.bak
2. a temp file is created, HOSTS_DENY.migrate.tmp
3. the HOSTS_DENY is parsed and each entry that is commented or is a blank link will be written to HOSTS_DENY.migrate.tmp as-is.
4. otherwise, each HOSTS_DENY entry will have a comment added in the form of # DenyHosts: timestamp and then written to HOSTS_DENY.migrate.tmp
5. after all lines are parsed, HOSTS_DENY.migrate.tmp is moved to HOSTS_DENY (atomically-- such that even in the case of failure, the HOSTS_DENY should always be present). In the event of a catastrophic emergency you can manually move the HOSTS_DENY.migrate.bak back to HOSTS_DENY.

Note:
If you have a manually added specific hosts to HOSTS_DENY (without the use of DenyHosts, for instance) then you may wish to edit HOSTS_DENY and remove the timestamp data that was appended to the line by the --migrate function. You may also wish to do this for any entry that you never want DenyHosts to remove. Any timestamped entry will automatically be removed by DenyHosts when it is invoked with the --purge flag subject to the PURGE_DENY value. Refer to the purge section for more details.

Return to top

A. 3.13

How can I prevent more than one instance of DenyHosts from running?

In the event that something goes awry (or if you savagely killed the current DenyHosts process before it had a chance to delete the LOCK_FILE itself) there is a chance that the LOCK_FILE will not get deleted. If this occurs, you can manually clear the LOCK_FILE by invoking DenyHosts with the --unlock flag:

$ denyhosts.py --unlock

Return to top

A. 3.14

Why does DenyHosts report "Error sending email"?

Error sending email
{'foo@localhost': (504, '<DenyHosts>: Sender address rejected: need fully-qualified address')}

If you do receive this error message simply edit your configuration file and enter a fully qualified email address for the SMTP_FROM parameter. For instance:

SMTP_FROM = DenyHosts <nobody@yourdomain.com>

Return to top

A. 3.15

Can DenyHosts email reports to SMTP servers that require authentication?

• SMTP_USERNAME - your SMTP username.
• SMTP_PASSWORD - your SMTP password.

A. 3.16

Can DenyHosts be run as a daemon (background) process?

$ denyhosts.py --daemon Note:
The following command line flags are ignored when --daemon is used: --file, --verbose, --migrate, --purge

Note:
The daemon mode must be invoked as superuser (root)

There are 3 optional configuration settings specific to daemon mode. You can refer to the included denhosts.cfg-dist file for sample usage. These new values are:

1. DAEMON_LOG: specifices the path to which DenyHosts should record activity. The default is /var/log/denyhosts
2. DAEMON_SLEEP: the amount of time that DenyHosts will pause between checking for new activity in your SECURE_LOG. The default is 30s
3. DAEMON_PURGE: the amount of time that DenyHosts should attempt to purge historical entries from your HOSTS_DENY file. If left blank, purging will be disabled. The default is 1h

For your convenience there is a python script daemon-control-dist that is located in the DenyHosts distribution. You should copy this file to daemon-control and edit the 3 variables at the top to match your environment. If you wish you can place this in your /etc/init.d directory.

You can then invoke this script to control the DenyHosts daemon:

• daemon-control start - stats DenyHosts in daemon mode
• daemon-control stop - cleanly stops the DenyHosts daemon
• daemon-control restart - stop and start the daemon
• daemon-control debug - Instructs the daemon to toggle between the debug and normal log output
• daemon-control status - display the state of the daemon

$ daemon-control start --config=test.cfg

To restart the above example in debug mode:

$ daemon-control restart --config=test.cfg --debug

Return to top

A. 3.17

I have additional questions, where can I get help?

or

You can contact me directly.

Return to top

A. 3.18

I've found a bug, will you fix it?

In the rare and highly unlikely event that you do find what you think might be considered a bug (even though it's really a feature) you can report it at Sourceforge.

When reporting a bug, please try to include the output from DenyHosts when invoking it with the --debug flag:
$ denyhosts.py --debug

Alternatively, You can send the bug report to my Sourceforge email address.

Return to top

A. 3.19

How can I remove an IP address that DenyHosts blocked?

1. Stop DenyHosts
2. Remove the IP address from /etc/hosts.deny
3. Edit WORK_DIR/hosts and remove the lines containing the IP address. Save the file.
4. Edit WORK_DIR/hosts-restricted and remove the lines containing the IP address. Save the file.
5. Edit WORK_DIR/hosts-root and remove the lines containing the IP address. Save the file.
6. Edit WORK_DIR/hosts-valid and remove the lines containing the IP address. Save the file.
7. Edit WORK_DIR/user-hosts and remove the lines containing the IP address. Save the file.
8. (optional) Consider adding the IP address to WORK_DIR/allowed-hosts
9. Start DenyHosts

Note: Not all of the WORK_DIR files will contain the IP address so you may want to use grep to determine which files contain the IP address.

Return to top

A. 3.20

What are all of the files in my DenyHosts WORK_DIR?

User maintained files (they are optional)

allowed-hosts - contains a list of ip addresses that are exempt from being denied by DenyHosts. For further details refer to the allowed hosts FAQ entry.

restricted-usernames - contains a list of real or ficticious usernames that should never log into your sshd server. Refer to restricted usernames for more information.

DenyHosts maintained files

offset - DenyHosts stores the offset of the last position read from your SECURE_LOG file. DenyHosts uses this to quickly determine if new data is available in your logfile. This file also stores the first line of your log file such that DenyHosts can determine if the file has been rotated between scans.

purge-history - (new in 2.4) contains a list of the denied hosts that have been purged from your HOSTS_DENY file. Additionally, this file records the number of times this host has been purged and the timestamp of the most recent purge. This file is only created if DenyHosts is operating in purge mode.

sync-received - a list of the hosts that have been received from the DenyHosts Synchronization server. Refer to sync mode for more details.

sync-timestamp - the last time that synchronization has occurred. Refer to sync mode for more details.

hosts - a list of all hosts that have attempted to access your sshd server. In addition the file contains the number of failed attempts and most recent attempt timestamp.

hosts-restricted - a list of hosts that have attempted to access restricted username accounts on your server. The file has the same format as hosts.

hosts-root - a list of hosts that have attempted to access the root account on your server. The file has the same format as hosts.

hosts-valid - a list of hosts that have attempted to access valid username accounts on your server. The file has the same format as hosts.

suspicious-logins - a list of suspicious login activity (that is, logins that were successful after the deny threshold should have been reached).

users-hosts - a list of usernames along with the ip address that attempted to login to your sshd server. This file also contains the number of attempts for the username/ip address along with the most recent timestamp.

users-invalid - a summary of non-existent usernames that were used in order to login to your server. The file also contains the number of attempts per usernames and the most recent timestamp.

users-valid - a summary of all existing usernames (including 'root') that attempts to login to your sshd server. The file also contains the number of attempts per usernames and the most recent timestamp.

Return to top

DenyHosts Synchronization Mode

A. 4.0

What is synchronization mode?

This feature is intended to provide the ability to proactively deny ip addresses that have attacked other users of DenyHosts. That is, each DenyHosts 2.0 (or later) user can benefit from other users of Denyhosts. Similarly each DenyHosts user can benefit other DenyHosts users.

Return to top

A. 4.1

What is denyhosts.net?

A. 4.2

How does synchronization mode work?

Each time that your DenyHosts daemon connects to the denyhosts.net server, only the data that has changed since the last data synchronization is transmited.

Return to top

A. 4.3

What are the requirements for synchronization mode?

A. 4.4

Is synchronization mode enabled by default?

A. 4.5

How do I enable synchronization mode?

Note: If you are upgrading DenyHosts to 2.0 (or later) from v1.x then you will need to add several parameters to the configuration file. The denyhosts.cfg-dist file contains several new parameters for synchronization mode. These parameters should be manually copied to your DenyHosts configuration file.

The parameters pertaining to synchronization mode support are prefixed with SYNC_. They are:

• SYNC_SERVER - required
• SYNC_INTERVAL
• SYNC_UPLOAD
• SYNC_DOWNLOAD
• SYNC_DOWNLOAD_THRESHOLD
• SYNC_DOWNLOAD_RESILIENCY - (version 2.1 or later)

If the SYNC_SERVER parameter is not defined then synchronization mode will be disabled.

Note: by default synchronization mode is disabled. To enable it (recommended) you must add the following to your configuration file:

SYNC_SERVER = http://xmlrpc.denyhosts.net:9911

The other synchronization mode parameters are optional.

Return to top

A. 4.6

How do I configure synchronization mode?

SYNC_INTERVAL - Specifies the length of time between synchronization attempts. By default, this value is 1 hour. The minimum allowed value is 5 minutes. If your DenyHosts daemon has not recorded any additional rogue hosts since the previous synchronization then no data will be uploaded to denyhosts.net. If no new DenyHosts (that meet your SYNC_DOWNLOAD_THRESHOLD and >SYNC_DOWNLOAD_RESILIENCY settings) are available from the denyhosts.net server, then no hosts will be downloaded by your daemon.

SYNC_UPLOAD - Allow your DenyHosts daemon the ability to upload data. The default is "yes".

SYNC_DOWNLOAD - Allow your DenyHosts daemon the ability to transmit data. The default is "yes".

SYNC_DOWNLOAD_THRESHOLD - Only download recently denied hosts that have been blocked by this number of other DenyHosts daemons.

SYNC_DOWNLOAD_RESILIENCY - Only download ip addresses that have been attacking other servers for atleast this length of time.

Return to top

A. 4.7

Can I just send denied data?

SYNC_DOWNLOAD = no

Return to top

A. 4.8

Can I just receive data?

SYNC_UPLOAD = no

Return to top

A. 4.9

When receiving denied data will I get all denied hosts?

Subsequently, subject to your SYNC_INTERVAL setting, when your DenyHosts daemon connects with the denyhosts.net server only the data that has changed since it's last connection will be transmitted. That is, if there are a total of 1000 denied hosts in the system but only 5 have been added (or re-added) since the last synchronization, then only the 5 will be transmitted to your DenyHosts daemon.

Additionally, you can set your SYNC_DOWNLOAD_THRESHOLD to qualify the data being transmitted such that you have more confidence in it. That is, each time a host is added to the denyhosts.net server a counter is incremented for that ip address. If your SYNC_DOWNLOAD_THRESHOLD = 1 and the counter for an ip address is 1 (that is, a single DenyHosts daemon transmitted this address) then your DenyHosts daemon would download it. However, if your SYNC_DOWNLOAD_THRESHOLD = 4 then your DenyHosts daemon would not download this ip address until 3 other DenyHosts clients transmitted the data.

DenyHosts 2.1 adds the SYNC_DOWNLOAD_RESILIENCY setting. Resiliency is defined as the timespan between a hackers first known attack and it's most recent attack. This value is used in conjunction with the SYNC_DOWNLOAD_THRESHOLD value and only hosts that satisfy both values will be downloaded. This value has no effect if SYNC_DOWNLOAD_THRESHOLD = 1.

Example:

If the centralized denyhosts.net server records an attack from an ip address at 12 PM and then again at 2 PM, the resiliency of the offending ip address is 2 hours. Specifying a SYNC_DOWNLOAD_RESILIENCY = 4h (4 hours) will not download this ip address. However, if the attacker is recorded again at 5 PM then the ip address will be downloaded by your DenyHosts instance since the ip address has been resilient for 5 hours (12 PM until 5 PM).

Return to top

A. 4.10

How do I know that DenyHosts synchronization mode is working?

Feb 04 07:42:51 - sync        : INFO     received 0 new hosts
Feb 04 07:52:52 - sync        : INFO     sent 1 new host
Feb 04 07:52:52 - sync        : INFO     received 0 new hosts
Feb 04 08:02:52 - sync        : INFO     received 1 new host

A. 4.11

I decided that I don't want to use synchronization mode, how do I disable it?

A. 4.12

How long will retrieved ip addresses remain in my HOSTS_DENY file?

If the optional PURGE_THRESHOLD (new in v2.4) value is defined and not 0 (zero) then a host will be purged atmost this many times. That is, if this value is set to 3, then DenyHosts will purge a host atmost 3 times. After the host has been purged 3 times the host will remain in your HOSTS_DENY forever, effectively blocking it forever (unless you change this setting). If this value is set to 0 (the default) then DenyHosts will purge each host indefinitely (that is, each host can be added and purged repeatedly without being blocked permanently).

Return to top

A. 4.13

What is the cost of the synchronization service?

A. 4.14

What information is collected from me?

If you enable synchronization uploads, then, in addition to your ip address being sent, all recently denied ip addresses that your DenyHosts daemon has thwarted will be transmitted. This is of course the desired behavior and provides all DenyHosts daemons (that have synchronization download enabled) the ability to proactively block rogue hosts.

Return to top

A. 4.15

How will information collected from me be used?

The hosts that your DenyHosts daemon denies will of course be shared with other DenyHosts daemons. Additionally, this data may be shared with 3rd parties at the discretion of the creator of DenyHosts.

Return to top

A. 4.16

What is the acceptable use policy of the data that denyhosts.net provides?

A. 4.17

I administer many commercial servers, can I run my own denyhosts.net server?

Currently, the server that denyhosts.net uses to interact with DenyHosts daemons is not publicly available. You may contact me if you would like to license the server component.

Return to top