countm

Byron Young

Jan 7, 2006

Abstract

countm is a simple utility to list, insert, and delete link entries within mod_countm database files.

1  The Command Line

countm [DB4_OPTIONS] -dbenv= -dbfile= [OPTIONS] COMMAND
countm [MySQL_OPTIONS] -user= -db= [OPTIONS] COMMAND
OPTIONS are all command line items beginning with a dash (-), up to, but not including, COMMAND.
COMMAND identifies the command to process.

2  Command Line COMMAND

COMMAND is exactly one of [L,LIST], [I,INSERT], or [D,DELETE].
Only the first letter is significant.

3  Command Line COMMAND - LIST

List information from the specified database(s).
Returns true (0) if listing is successful.

3.1  List DB_COUNTER

countm [-x] -dbc L

List all links in DB_COUNTER. Used to generate a list of links in DB_COUNTER for scripts. The -x adds header information and the DB_COUNTER information associated with link.
[apache] countm -dbenv=/var/countm/dbase -dbfile=countm.db -dbc L
one
two
http://www.mydomain.com/b+ +stuff/index.html

[apache] countm -dbenv=/var/countm/dbase -dbfile=countm.db -dbc -x L
LINK:one
DB_COUNTER:
cnt=23
image=jpeg
count=norm_inc
random=false
atime=2005-03-09
width=0
point=18
bgcolor=tn_ss.jpeg
text=FFFFFF
font=FreeMono.ttf
LINK:two
DB_COUNTER:
cnt=23
image=jpeg
count=inc_nopub
random=true
atime=2005-03-09
width=6
point=18
bgcolor=tn_ss.jpeg
text=FFFFFF
font=FreeMono.ttf
LINK:http://www.mydomain.com/b+ +stuff/index.html
DB_COUNTER:
cnt=23
image=jpeg
count=norm_inc
random=false
atime=2005-03-09
width=0
point=18
bgcolor=tn_ss.jpeg
text=FFFFFF
font=FreeMono.ttf

countm [-x] -dbc -l=linkname L

List information for specific link linkname from DB_COUNTER. Used to generate DB_COUNTER information for a specific link. The -x adds header information, and the linkname itself.
[apache] countm -dbenv=/var/countm/dbase -dbfile=countm.db -dbc -l=one L
cnt=23
image=jpeg
count=norm_inc
random=false
atime=2005-03-09
width=0
point=18
bgcolor=tn_ss.jpeg
text=FFFFFF
font=FreeMono.ttf
\end{verbaim}

\begin{verbatim}
[apache] countm -dbenv=/var/countm/dbase -dbfile=countm.db -x -dbc -l=one L
LINK:one
DB_COUNTER:
cnt=23
image=jpeg
count=norm_inc
random=false
atime=2005-03-09
width=0
point=18
bgcolor=tn_ss.jpeg
text=FFFFFF
font=FreeMono.ttf

countm [-x] L
countm [-x] -dbc -dba L

List all links from DB_COUNTER, with DB_ACCESS information. Not really useful. The -x adds header information, the linkname, and the DB_COUNTER information associated with each link. Used to dump the entire database.
[apache] countm -dbenv=/var/countm/dbase -dbfile=countm.db -x L
LINK:one
DB_COUNTER:
cnt=23
image=jpeg
count=norm_inc
random=false
atime=2005-03-09
width=0
point=18
bgcolor=tn_ss.jpeg
text=FFFFFF
font=FreeMono.ttf
DB_ACCESS:
laptop.localzone
techguy.localzone
waiter.localzone
LINK:two
DB_COUNTER:
cnt=23
image=jpeg
count=inc_nopub
random=true
atime=2005-03-09
width=6
point=18
bgcolor=tn_ss.jpeg
text=FFFFFF
font=FreeMono.ttf
DB_ACCESS:
laptop.localzone
techguy.localzone
waiter.localzone
LINK:http://www.mydomain.com/b+ +stuff/index.html
DB_COUNTER:
cnt=23
image=jpeg
count=norm_inc
random=false
atime=2005-03-09
width=0
point=18
bgcolor=tn_ss.jpeg
text=FFFFFF
font=FreeMono.ttf
DB_ACCESS:
laptop.localzone
techguy.localzone
waiter.localzone

[apache] countm -dbenv=/var/countm/dbase -dbfile=countm.db L
one
laptop.localzone
techguy.localzone
waiter.localzone
two
laptop.localzone
techguy.localzone
waiter.localzone
http://www.mydomain.com/b+ +stuff/index.html
laptop.localzone
techguy.localzone
waiter.localzone

countm [-x] -l=linkname L
countm [-x] -dbc -dba -l=linkname L

List all information from DB_COUNTER for specific linkname, with DB_ACCESS information. Not really useful. The -x add header information, and outputs the linkname. Used to edit a specific links information by creating a text file to edit, then inserted back into the database.
[apache] countm -dbenv=/var/countm/dbase -dbfile=countm.db -l=one L
cnt=23
image=jpeg
count=norm_inc
random=false
atime=2005-03-09
width=0
point=18
bgcolor=tn_ss.jpeg
text=FFFFFF
font=FreeMono.ttf
laptop.localzone
techguy.localzone
waiter.localzone

[apache] countm -dbenv=/var/countm/dbase -dbfile=countm.db -x -l=one L
LINK:one
DB_COUNTER:
cnt=23
image=jpeg
count=norm_inc
random=false
atime=2005-03-09
width=0
point=18
bgcolor=tn_ss.jpeg
text=FFFFFF
font=FreeMono.ttf
DB_ACCESS:
laptop.localzone
techguy.localzone
waiter.localzone

3.2  List DB_ACCESS

countm -dba L

List all links in DB_ACCESS. Used by scripts to get a list of all links in DB_ACCESS.
[apache] countm -dbenv=/var/countm/dbase -dbfile=countm.db -dba L
one
two
http://www.mydomain.com/b+ +stuff/index.html

countm -x -dba L

List all links in DB_ACCESS and the hostnames associated with each link. Also adds header information. Used to dump DB_ACCESS but rarely required.
[apache] countm -dbenv=/var/countm/dbase -dbfile=countm.db -dba -x L
LINK:one
DB_ACCESS:
laptop.localzone
techguy.localzone
waiter.localzone
LINK:two
DB_ACCESS:
laptop.localzone
techguy.localzone
waiter.localzone
LINK:http://www.mydomain.com/b+ +stuff/index.html
DB_ACCESS:
laptop.localzone
techguy.localzone
waiter.localzone

countm [-x] -dba -l=linkname L

List all the host names associated with linkname. Used by scripts to list all hostnames associated with a link. -x adds some headers, and outputs the linkname. Rarely used.
[apache] countm -dbenv=/var/countm/dbase -dbfile=countm.db -dba -l=one L
laptop.localzone
techguy.localzone
waiter.localzone

[apache] countm -dbenv=/var/countm/dbase -dbfile=countm.db -x -dba -l=one L
LINK:one
DB_ACCESS:
laptop.localzone
techguy.localzone
waiter.localzone

4  Command Line COMMAND - INSERT

Insert information from a formatted text file into database. Return true (0) if insertion succeeds, false (error code) otherwise. Normally, this file is created with the L(ist) command.
countm -f=filename I

Returns true (0) if insertion is successful, false (error code) otherwise.
If the link(s) are currently in DB_COUNTER, the data from filename overwrites the data currently in DB_COUNTER. The hostnames associated with a link are added to the DB_ACCESS list for associated link(s). The values currently associated with a links DB_ACCESS list remain unchanged.

5  Command Line COMMAND - DELETE

Permanently deletes information associated with a link from the database(s). The -x parameter is ignored.
countm -l=linkname D
countm -dbc -dba -l=linkname D

Deletes all information associated with a specific link from DB_COUNTER and the links access list from DB_ACCESS. If the link is in neither DB_COUNTER or DB_ACCESS, CM_NO_LINK is returned. This is the normal use of countm delete.
countm -dbc -l=linkname D

Deletes all the information associated with a specific link from DB_COUNTER. If linkname is not in DB_COUNTER, CM_NO_LINK is returned.
countm -dba -l=linkname D

Deletes all the access list information associated with a specific link from DB_ACCESS. If linkname is not in DB_COUNTER, CM_NO_LINK is returned.
countm -dba -h=hostname -l=linkname D

Deletes the specific hostname from the links DB_ACCESS access list. If link and/or hostname is not in DB_ACCESS, CM_NO_LINK is returned.
countm -dba -h=hostname D

Deletes the the specific hostname from all links (in DB_ACCESS) DB_ACCESS access list. If hostname is not associated with any link in DB_ACCESS, CM_NO_LINK is returned.

6  DB4_OPTIONS

The two required DB4_OPTIONS are:
-dbenv identifies the DB4 environment to use.
-dbfile identifies the DB4 database file (within dbenv) to use.

7  MySQO_OPTIONS

The MySQL_OPTIONS (two are required) are:
-user= (Required) Identifies the MySQL user ID.
-db= (Required) Identifes the MySQL database to use.
-host= Identifies the MySQL host name.
-passwd= Identifies the MySQL user ID password.
-port= The port to connect. Normally not required.
-unix_socket= The socket to connect. Normally not required.
-opt_group= The group name of extra options within a file.
-opt_file= The file name to access when connecting to database with options.

8  Command Line Options

8.1  -dba

-dba Apply operation to DB_ACCESS.

8.2  -dbc

-dbc Apply operation to DB_COUNTER.

8.3  -l=linkname

-l=linkname Use this linkname. A -l= empty string is the same as not using the -l option.

8.4  -l=hostname

-h=hostname Use this hostname. A -h= empty string is the same as not using the -h option. Only valid with the -dba option.

8.5  -x

-x Extended listing.

8.6  -f=filename

-f=filename Use this file as an input file. A -f= empty string is the same as not using the -f option.

8.7  -dbenv=/path/to/dbenv

-dbenv=/path/to/dbenv

8.8  -dbfile=database_file

-dbfile=database_file The name of the counter database file, within dbenv.

8.9  -V

-V print version information and exit.

8.10  -?

-? Print help message and exit.

9  Return Codes

RETURN CODES
 0 = success (true)
 1 = no link in database(s)/ database(s) empty. (false)
 2 = database error. (false)
 3 = Invalid parameter given. (false)
 4 = A duplicate parameter was given. (false)
 5 = No host was in database. (false)
 6 = File error. (false)
 7 = Input file syntax error. (false)
 8 = Invalid linkname. (false)
 9 = Memory error. (false)

10  Usage Notes

Some important utility usage notes.

10.1  The Database

See the mod_countm manual for a complete description of the database. To summerize, within an environment, one or more database files may exist. Each database file contains two sub databases: DB_COUNTER and DB_ACCESS. Sub database DB_COUNTER maintains, for each link, the count value and default parameter values. Sub database DB_ACCESS maintains, for each link, an access list ( a listing of all accessing remote hosts.)

10.2  DB4 Database Locking

The countm utility process and the mod_countm threads of control coordinate database access via a "countm utility master lock" and a environment file lock.
The countm utility may only aquire the master lock when no mod_countm thread of control has been granted the master lock. The mod_countm threads of control are always granted the master lock unless the countm utility has been granted the master lock. This means that while the countm utility is running, no mod_countm thread of control may access the database.
A possible lock conflict may arise if the countm utility and a mod_countm thread of control attempt to create the environment and databases simultaneously.
If the countm utility and/or the mod_countm server crashes (shuts down incorrectly, or other reason) the env.lck file or the environment must be removed manually.

10.3  DB4 Creating Databases

When run with the same permissions as the Apache runtime server, the countm utility may create environment and databases. Due to the environment lockfile access situation, however, avoid using the countm utility to create environments and databases.

10.4  MySQL Database Locking

Each query aquires a lock on both DB_ACCESS and DB_COUNTER tables. Locks are automatically released on connection close.

10.5  MySQL Creating the Database

The countm utility will attempt to create the MySQL database and tables if the countm utility successfully connects to the MySQL database, but cannot select the -db= database. The -user= must have create table permissions. Just as a note, if an existing database was deleted incorrectly, any create database attempt will fail. When deleteing databases manually, always delete the table entries first, then the tables, then the database. By looking at the physical location on the filesystem of the MySQL server database files, and existing directory with the deleted database name is a sure sign that the database was deleted improperly.
The help option will print out the MySQL statements used to create the database and tables.
The countm utility does not have to be run with any special user permissions.
Using the countm utility to create the MySQL database and tables is recommended.
After a new install, running the countm utility with just the L command will create the database and tables, the list nothing.

10.6  MySQL Database - Fine Tuning

Unlike mod_countm, the countm utility, depending on the command, may access the entire DB_COUNTER and/or DB_ACCESS table. To control, to some extent, the amount of information requested per statement, use the countm_util.h compile time COUNTM_MYSQL_SELECT_ROWS option.
The compile time option COUNTM_MYSQL_SELECT_ROWS determines the number of rows retrieved from the MySQL Database each request. A 0 setting will select all results in one request (excellent for low traffic sites.) A larger number will create larger network packets, but result in fewer database requests. Smaller numbers will result in smaller packets, but more database reqeusts. Use this in conjuctions with the MySQL Database Administration System Server Variable max_allowed_packet.
In some situations, the MySQL C API data type my_ulonglong is printed out using the printf "%llu" format. If a particular libc implementation does not implement this, all instances should be changed to "%lu".

10.7  Linkname and Hostname encoding

countm does not encode, decode, or process in any manner linkname and hostname parameter values. The command line linkname and hostname parameter values should be stated exactly as their actual values, without any encoding. A generated listing of all entries in the database will print the linkname and hostname exactly as they should be entered on the commandline.

10.8  Editing A Database Entry

The most common usage of countm is editing a database entry.
First, generate a complete listing for the linkname.
countm -dbenv=/var/countm/dbase -dbfile=countm.db -dbc -dba -l=linkname -x LIST > out.txt

Next, use a favorite text editor to edit each line in out.txt as desired, then insert the entry back into database.
countm -dbenv=/var/countm/dbase -dbfile=countm.db -f=filename INSERT

The values currently in the database will be overwritten with the new values from the text file.

10.9  Deleting A Database Entry

See Delete A Specific Link.

10.10  Inserting A Database Entry

Countm may be used to insert link entries. The easiest method is to edit a listing of a link already in the database, being certain to alter LINK: to the new value, then use that listing as the -f parameter of the INSERT command.

10.11  Output

All database errors are output to stderr.
All program output is to stdout.

11  INPUT File Format

The following is a brief definition of the INPUT (-f=) file.

11.1  Basic Format

The basic format of the input command (-f=) file is as follows:

11.2  Section Definition

A section consists of three subsections; The linkname section, the DB_COUNTER section, and the DB_ACCESS section.
The linkname subsection is exactly one statement: "LINK:linkname".
The DB_COUNTER subsection begins with (exactly) the statement "DB_COUNTER:", and ends when the DB_ACCESS subsection begins.
The DB_ACCESS subsection begins with (exactly) the statement "DB_ACCESS:", and ends at EOF or the beginning of a new section.

11.3  Subsection linkname

A section must begin with a "LINK:linkname" statement. The linkname is associated with all data in the section. This implies that the first line of a file must be a LINK:linkname statement.

11.4  Subsection DB_COUNTER

The DB_COUNTER subsection immediately followings the linkname subsection. The first statement of a DB_COUNTER subsection must be "DB_COUNTER:". This implies that the second line in a file must be a DB_COUNTER: statement. Each line in the DB_COUNTER subsection is a item=value statement. A "notdef" value is the same as a missing statement. Valid items are:

11.5  Subsection DB_ACCESS

Immediately following the DB_COUNTER subsection is the DB_ACCESS subsection.The first statement of a DB_ACCESS subsection is "DB_ACCESS:". All subsequent statements, upto, but not including the EOF or the next linkname subsection statement (which begins a new section), will be assumed to be a hostname, and inserted directly into the links DB_ACCESS access list.

12  A Minimal Input File

LINK:linkname
DB_COUNTER:
DB_ACCESS:

13  A Typical Input File

LINK:linkname
DB_COUNTER:
cnt=0
font=FreeMono.ttf
image=img_jpeg
count=norm_inc
random=random_false
width=0
point=20
bgcolor=9933FF
text=FFFFFF
DB_ACCESS:
localhost
localhost.localdomain




File translated from TEX by TTH, version 3.40.
On 7 Jan 2006, 15:48.