docsis_server How To

Config File Settings

# This is the config file for the docsis_server for
# DOCSIS cable modems and customer PC equipment.
#
# It includes a DHCP server, a TFTP server, a UDP TIME
# server and SYSLOG server.

# This file needs to be located at /etc/docsis-server.conf

# If you are upgrading from a previous version and just want
# to test this new server you can name the file
# /etc/docsis-server2.conf
# and then you can run the old version again if you need to.


Server-Name     my-server
Admin-Email     admin_email_address@example.com


# The effective userid that the server will run with.
# I recommend you install the "docsis" user with the
# INSTALL.uid script
Effective-UserID   docsis


# The following settings are either (yes or no)
Activate-DHCP    yes
Activate-TFTP    yes
Activate-TIME	yes
Activate-SYSLOG	yes
Activate-BACKG	yes
#Activate-FakeWeb no  future use


# Ethernet device to use dhcp server on.
DHCP-Interface	eth0


#The location of your modem config files.
TFTP-Dir        /home/cable_modem_tftp


# If you want to double check the dynamic config files
# that are being created you can set this setting to YES
# and create a "dynamic" directory in your TFTP-dir.
# It must be owned by your Effective-UserID
Dynamic-Config-Debug	no


# Secret Key for Dynamic Config File authorization
Config-Secret-Key	Secret-Key


# When a file goes unused in the TFTP file cache
# it will eventually be deleted from memory.
# This option sets that delete time in seconds.
# If you have a small set of generic files you can
# safely increase this to 86400.
# If you have a different config file for every modem
# you can lower this number to 300.
TFTP-Cache-Time		3600


# Dynamic config files are also cached but since you have
# a different file for each modem you don't want to cache
# for very long. If you have a low memory server you should
# reduce this quite a bit.
TFTP-Dynamic-Cache-Time	60


# You need to specify a MySQL server host, user, password, database
Mysql-Host		localhost
Mysql-User		mysql_user
Mysql-Password		easy_password
Mysql-DHCP-Database	dhcp_server
Mysql-Syslog-Database	syslog_server


# If the system load average is greater than or equal to this value
# any Database Querys / Updates will be collected and sent through
# after the load average goes down. If you choose 'no' for Suspend-Updates
# the system will always do updates
Suspend-Load-Avg                2.0

Suspend-system-Logging          yes
Suspend-dhcp-Logging            yes
Suspend-tftp-Logging            yes
Suspend-syslog-Logging          yes


# The DHCP server has a cache of cable modem IPs that it can use
# instead of doing SQL queries. This can greatly speed up the
# DHCP server when you have a lot of modems trying to reaquire.
# There are 2 parameters. Load selects the system load average that
# the cache will turn on. When load average is still low (it is only
# checked every 1 or 2 minutes) the cache will take effect when
# the server has taken however many Hits in one second.
Modem-Cache-Load		0.75
Modem-Cache-Hits		5


# When something bad happens we will call this program.
# 1: When we run out of IP addresses
# We use a special pager gateway to notify our on-call staff
# The program has to sit in /tmp because we are chroot jailed there.
Alert-Program           alert-program


# The following settings allow you to automagically summerize the
# dhcp_log, tftp_log, sys_log and the syslog_server tables.
# If you don't want to summerize a log set the days to zero.
dhcp-summerize-days     60
tftp-summerize-days     60
sys-summerize-days      60
syslog-summerize-days   15

dhcp-delete-logs-days   120
tftp-delete-logs-days   120
sys-delete-logs-days    120
syslog-delete-logs-days 60


# Everything else is configured via tables.
# Read the INSTALL-Mysql document for more info.

server-name
admin-email
If you run multiple sites the server name helps you identify which server this is. There are a few perl scripts included that send emails to the admin-email address with the server-name in the subject line.
Currently these consist of monitoring of the IP pools, but future version will also include monitoring of the log tables to find problems.
effective-userid
The docsis_server needs to be started by root, but after starting it can shed this privileged mode for a less privileged id.
The "INSTALL.uid" script can install this user id for you or you can use your own special username here.
activate-dhcp
activate-tftp
activate-time
activate-syslog
activate-backg
The docsis_server consists of 5 seperate daemons. If you don't wish to run 1 or more of them (If you have your own syslog or tftp server) you can disable them in the config file.
The BackG server monitors your config file fragments and regenerates them if they are updated.
dhcp-interface
This version requires that you select which ethernet interface you want to bind the DHCP server to. I hope to remove this limitation in the future, but for now you need to select the interface. ie. "eth0" etc.
tftp-dir
When the servers start up they will all change their directory root to '/tmp' except for the TFTP server which will chroot to this directory setting. This directory should contain all the config files necessary for your DOCSIS cable modems to boot up.
dynamic-config-debug
If you want to double check the dynamic config files that are being pieced together and sent to your modems, set this option to yes. You must have a "dynamic" directory in your tftp-dir. This is only used for dyanamic generated config files.
config-secret-key
If you use static config files for CM don't worry about this. If you use the new dynamic config file generator you need to supply the shared "secret" you are using to authenticate your config files.
tftp-cache-time
When a file is requested via TFTP it is read into memory (RAM) and held there until it is either updated or if it hasn't been accessed for a certain number of seconds. This option lets you set the number of seconds the file will remain in memory if it is not accessed.
If you have a small set of generic config files for you different QoS settings you should set this to a fairly large value (86400 secs = 1 day).
If you have a large number of very specific config files (ie 1 unique file per cable modem) you should set this to a very low value so that it will expire an unused file quickly (300 secs = 5 min). If you have lots of RAM then don't worry about it, but keep in mind that the disk space taken up by all your config files may go into memory.
tftp-dynamic-cache-time
This is usually a small value of 60 seconds or so. If you have a CMTS reboot, it will be cache 1 file for each modem. They are not usually that big, but it can be a concern.
Mysql-Host
Mysql-User
Mysql-Password
Mysql-dhcp-Database
Mysql-syslog-Database
The docsis_server needs the Mysql Database server. The config file must contain the username and passwords necessary to log in. The next HOWTO document explains how to setup the DB.
You can name the databases anything you want to. You can run multiple servers from 1 database server and/or multiple databases.
Suspend-Load-Avg
At the specified load average, the server will stop hitting the MySQL server so often. Each request/update introduces a small latency that we sometimes wish to avoid. When the CMTS resets you want all the modems to come back online as fast as possible. These updates will be stored in memory until the load goes down. If you set this value too low it will suspend logging and die a couple hours (or days) later when it uses up all your RAM.
Suspend-system-Logging
This will suspend SQL inserts to the dhcp_server.sys_log table. This table contains messages and errors from the 4 different servers.
Suspend-dhcp-Logging
This will suspend SQL inserts to the dhcp_server.dhcp_log table. This table contains the MAC and IP of all the DHCP transactions.
Suspend-tftp-Logging
This will suspend SQL inserts to the dhcp_server.tftp_log table. This table contains the IP and file name of all TFTP transactions.
Suspend-syslog-Logging
This will suspend SQL inserts to the syslog_server.log_*. The syslog_server database has a table names based on the current date ie. log_2003_7_21. The SYSLOG server is designed to accept messages from Cable Modems as well as various Cisco equipment.
Modem-Cache-Load
Modem-Cache-Hits
The Modem-Cache is an in-memory cache of all the cable modem MACs, IPs and config files. When the server is under heavy load (right after a CMTS reset) instead of doing an SQL lookup for every DHCP request it will use an in-memory cache of all the cable modems. The cache is reloaded every ten minutes so that we get the right config files. Most of the time it is more accurate to go directly to the SQL db, but when you have a few thousand modems to boot up you don't care if a couple of modems got new config files 5 minutes ago. When the system load average is above the Modem-Cache-Load the cache will be used. When the server receives more than Modem-Cache-Hits in 1 second it will use the cache for all the rest of the requests it receives that second. This option was included because the load average is only checked every 2 minutes.
dhcp-summerize-days
tftp-summerize-days
sys-summerize-days
syslog-summerize-days
dhcp-delete-logs-days
tftp-delete-logs-days
sys-delete-logs-days
syslog-delete-logs-days
The program "/usr/sbin/Summerize_Logs" is included to allow you to prune your log files. You can set the number of days you want to keep your logs here. If you don't run Summerize_Logs in your crontab it will not summerize or delete any of your logs. If you have a 60GB hard drive you won't have to worry for a couple years.