[apple/syslog.git] / syslogd.tproj / asl.conf.5

.Dd December 22, 2005
.Dt asl.conf 5
.Os "Mac OS X"
.Sh NAME
.Nm asl.conf
.Nd configuration file for
.Xr syslogd 8
asl_action module.
.Sh DESCRIPTION
The
.Xr syslogd 8
server in Mac OS X includes a module that compares messages with a set of query patterns,
and which performs various actions when messages match the query patterns.
.Pp
Each line in the file contains three components.
The first is a query, the second is an action, and the third contains parameters specific to that action.
For example:
.Pp
.Dl Q [= Sender foobar] [N< Level 3] notify com.apple.foobar
.Pp
.Ss Queries
Queries start with the letter "Q" followed by whitespace.
Following that are any number of message matching components, each of which has the form:
.Pp
.Dl [OP KEY VAL]
.Pp
OP is a comparison operator.
It can have the following values:
.Pp
.Bl -tag -width "<=  " -compact -offset indent
.It T
true (always matches)
.It =
equal
.It !
not equal
.It >
greater than
.It >=
greater than or equal to
.It <
less than
.It <=
less than or equal to
.El
.Pp
It can also be preceded by one or more modifiers:
.Bl -tag -width "C   " -compact -offset indent
.Pp
.It C
casefold
.It N
numeric comparison
.It S
substring
.It A
prefix
.It Z
suffix
.El
.Pp
KEY and VAL are message keys and values.
For example
.Pp
.Dl Q [= Sender foobar]
.Pp
matches any message with key="Sender" and val="foobar".
The query
.Pp
.Dl Q [CA= Color gr]
.Pp
matches any message with key=Color and val beginning with the letters GR, Gr, gr, or gR
(C meaning casefold, A meaning prefix).
The example query above,
.Pp
.Dl Q [= Sender foobar] [N< Level 3]
.Pp
matches any message from "foobar" with a level numerically less than 3
(string values are converted to integers, and the comparison is done on the integer values).
.Pp
The "T" operator is useful to test for the presence of a particular key.
.Pp
.Dl Q [T Flavor whatever]
.Pp
Will match any message that has a "Flavor" key, regardless of its value.
.Pp
.Ss Actions
The "notify" action causes
.Nm syslogd
to post a notification with
.Fn notify_post .
The notification key must appear as a single parameter following the "notify" action.
.Pp
The "access" action sets read access controls for messages that match the associated query pattern. 
.Nm syslogd
will restrict read access to matching messages to a specific user and group.
The user ID number and group ID number must follow the "access" keyword as parameters.
.Pp
The "store" action saves matching messages in a separate log message database.
The database may be accessed using the
.Nm syslog
command line utility.
A database pathname must follow the "store" keyword. 
A new database will be created if one does not exist.
Two optional parameters, "stayopen" and "exclude_asldb" may follow the database pathname.
.Pp
By default,
.Nm syslogd
will open the database, save a matching message, and then close the database.
If a high volume of messages is expected, specifying "stayopen" will improve performance.
.Pp
Specifying "exclude_asldb" will cause syslogd to save matching messages in the database,
but exclude them from the main 
.Nm syslogd
database (/var/log/asl.db).
.Sh SEE ALSO
.Xr asl 3 ,
.Xr notify 3 ,
.Xr syslog 1 ,
.Xr syslogd 8 .
Commit	Line	Data
5dd30d76 A	1	.Dd December 22, 2005
	2	.Dt asl.conf 5
	3	.Os "Mac OS X"
	4	.Sh NAME
	5	.Nm asl.conf
	6	.Nd configuration file for
	7	.Xr syslogd 8
	8	asl_action module.
	9	.Sh DESCRIPTION
	10	The
	11	.Xr syslogd 8
	12	server in Mac OS X includes a module that compares messages with a set of query patterns,
	13	and which performs various actions when messages match the query patterns.
	14	.Pp
	15	Each line in the file contains three components.
	16	The first is a query, the second is an action, and the third contains parameters specific to that action.
	17	For example:
	18	.Pp
	19	.Dl Q [= Sender foobar] [N< Level 3] notify com.apple.foobar
	20	.Pp
	21	.Ss Queries
	22	Queries start with the letter "Q" followed by whitespace.
	23	Following that are any number of message matching components, each of which has the form:
	24	.Pp
	25	.Dl [OP KEY VAL]
	26	.Pp
	27	OP is a comparison operator.
	28	It can have the following values:
	29	.Pp
	30	.Bl -tag -width "<= " -compact -offset indent
	31	.It T
	32	true (always matches)
	33	.It =
	34	equal
	35	.It !
	36	not equal
	37	.It >
	38	greater than
	39	.It >=
	40	greater than or equal to
	41	.It <
	42	less than
	43	.It <=
	44	less than or equal to
	45	.El
	46	.Pp
	47	It can also be preceded by one or more modifiers:
	48	.Bl -tag -width "C " -compact -offset indent
	49	.Pp
	50	.It C
	51	casefold
	52	.It N
	53	numeric comparison
	54	.It S
	55	substring
	56	.It A
	57	prefix
	58	.It Z
	59	suffix
	60	.El
	61	.Pp
	62	KEY and VAL are message keys and values.
	63	For example
	64	.Pp
65	.Dl Q [= Sender foobar]
66	.Pp
67	matches any message with key="Sender" and val="foobar".
68	The query
69	.Pp
70	.Dl Q [CA= Color gr]
71	.Pp
72	matches any message with key=Color and val beginning with the letters GR, Gr, gr, or gR
73	(C meaning casefold, A meaning prefix).
74	The example query above,
75	.Pp
76	.Dl Q [= Sender foobar] [N< Level 3]
77	.Pp
78	matches any message from "foobar" with a level numerically less than 3
79	(string values are converted to integers, and the comparison is done on the integer values).
80	.Pp
81	The "T" operator is useful to test for the presence of a particular key.
82	.Pp
83	.Dl Q [T Flavor whatever]
84	.Pp
85	Will match any message that has a "Flavor" key, regardless of its value.
86	.Pp
87	.Ss Actions
88	The "notify" action causes
89	.Nm syslogd
90	to post a notification with
91	.Fn notify_post .
92	The notification key must appear as a single parameter following the "notify" action.
93	.Pp
94	The "access" action sets read access controls for messages that match the associated query pattern.
95	.Nm syslogd
96	will restrict read access to matching messages to a specific user and group.
97	The user ID number and group ID number must follow the "access" keyword as parameters.
98	.Pp
99	The "store" action saves matching messages in a separate log message database.
100	The database may be accessed using the
101	.Nm syslog
102	command line utility.
103	A database pathname must follow the "store" keyword.
104	A new database will be created if one does not exist.
105	Two optional parameters, "stayopen" and "exclude_asldb" may follow the database pathname.
106	.Pp
107	By default,
108	.Nm syslogd
109	will open the database, save a matching message, and then close the database.
110	If a high volume of messages is expected, specifying "stayopen" will improve performance.
111	.Pp
112	Specifying "exclude_asldb" will cause syslogd to save matching messages in the database,
113	but exclude them from the main
114	.Nm syslogd
115	database (/var/log/asl.db).
116	.Sh SEE ALSO
117	.Xr asl 3 ,
118	.Xr notify 3 ,
119	.Xr syslog 1 ,
120	.Xr syslogd 8 .