- -d, --udp
-
データグラム (UDP) のみを使用する。デフォルトでは、
/etc/services で定義されている syslog
ポートに接続が試みられる。それは、たいてい 514 番である。
接続先の指定については、--server や --socket もご覧いただきたい。
- -e, --skip-empty
-
ファイルを処理する際に空行を無視する。空行とは、文字を一つも含まない行のことである。
従って、ホワイトスペースのみからなる行は、
空行とは見なされない。なお、--prio-prefix
オプションが指定された場合、優先度指定の部分は行の一部ではないことに気を付けていただきたい。
つまり、このモードでの空行とは、優先度を表す接頭辞
(たとえば、<13>) の後ろに文字が全く存在しない行のことである。
- -f, --file file
-
指定した file の内容をログに記入する。
このオプションは、コマンドラインにおけるメッセージ指定と併用することができない。
- -i
-
各行に logger プロセスの PID を記入する。
- --id[=id]
-
各行に logger プロセスの PID を記入する。指定が任意の引き数 id
を指定すると、それが logger コマンドの PID
の代わりに使用される。複数のメッセージを送出するスクリプトでは、--id=$$ (PPID)
を使用するとよい。
なお、システムのロギングを下支えしているものが (たとえば、
/dev/log をリッスンしている systemd が)、ローカルソケットの資格情報
(credentials) に従って、メッセージ中の指定された
PID を上書きしてしまうことがあるのに注意していただきたい。logger
は、そうしたソケットの資格情報の値を、指定された id
にすることができるわけだが、それは、ユーザがルート権限を持ち、しかも指定された
PID を持つプロセスが存在するときだけであって、
さもなければ、ソケットの資格情報は変更されず、その問題は暗黙裡に無視されるのである。
- --journald[=file]
-
systemd のジャーナルに書き込みをする。記入事項 (entry) は、file
を指定していれば、そのファイルから読み込まれ、指定していなければ、標準入力から読み込まれる。
各行は、journald の解するフィールドで始まっていなければならない。詳細については
systemd.journal-fields(7) をご覧いただきたい。MESSAGE_ID
フィールドを使用するのは、記入事項の検索を容易にするので、一般によい考えである。
例を二つ挙げよう。
-
logger --journald <<end
MESSAGE_ID=67feb6ffbaf24c5cbec13c008dd72309
MESSAGE=The dogs bark, but the caravan goes on.
DOGS=bark
CARAVAN=goes on
end
logger --journald=entry.txt
-
--journald は、たとえば優先度 (priority)
のような、他のオプションの値を無視することに注意していただきたい。
だから、優先度が必要なら、それを入力に含めなければならない。つまり、PRIORITY
フィールドを使用するのである。なお、単に journalctl を実行するだけだと、MESSAGE
フィールドしか表示されない。残りのフィールドも見るには、journalctl
--output json-pretty を使用すればよい。
MESSAGE に改行を入れるには (訳注: 言い換えれば、複数行にするには)、MESSAGE
を複数回指定する。これは、特例処理であり、複数回現れるのが他のフィールドの場合は、配列として
journal に格納されることになる。
- --msgid msgid
-
RFC5424 の MSGID フィールドを指定する。msgid
内ではスペース文字が使えないことに注意していただきたい。
このオプションが有効なのは、--rfc5424 も一緒に指定したときだけである。
そうでない場合は、黙って無視される。
- -n, --server server
-
システムログのソケットではなく、指定されたリモートの syslog サーバ、server
に書き込む。 --udp や --tcp が指定されていない場合、logger
は、まず UDP を使用しようとし、それに失敗すると、TCP 接続を試みる。
- --no-act
-
ログメッセージをシステムログに書き込むこと以外のすべてを実行し、
その後、ジャーナルへの接続を切る。このオプションは、テストのために
--stderr と一緒に使うことができる。
- --octet-count
-
メッセージの送信に RFC 6587 のオクテット計算フレーミングメソッド
(octet counting framing method)
を使用する。このオプションを使用しない場合、デフォルトのメソッドは、UDP
ではノーフレーミングであり、TCP では RFC6587 の非透過フレーミング
(octet stuffing としても知られる) である。
- -P, --port port
-
指定された port を使用する。このオプションが指定されない場合、
ポートはデフォルトが使われる。すなわち、UDP接続では syslog、TCP
接続では syslog-conn である。
- -p, --priority priority
-
指定された優先度 priority でログにメッセージを記入する。
優先度は、数値で指定してもよく、facility.level
の組み合わせで指定してもよい。たとえば、-p local3.info
と指定すると、ファシリティが local3、レベルは informational
としてメッセージが記録される。デフォルトは user.notice である。
-
- [訳注]
-
ファシリティ (facility) というのは、わかりにくい言葉だ。
だが、logger コマンドでは、ファシリティの値のそれぞれを、出力するメッセージの分類
(対象分野) ぐらいに考えておけばよいのではないかと思う。ファシリティが mail なら当然
mail 関係だし、auth ならセキュリティや認証関係のメッセージということだ。user や
local は、その他といったところだろうか。レベル (level) は「重大度、深刻度」。
そして、こうしたファシリティとレベルにより、/etc/syslog.conf
(または /etc/rsyslog.conf)
の設定に基づいて、出力先のログファイルが決まるわけである。
ファシリティやレベルの数値による表現については、
「ファシリティとレベル」セクションをご覧いただきたい。
なお、手元で試してみたところでは、この --priority
オプションでは、レベルを数値で指定することはできるが、
ファシリティを数値で指定することはできないようだ。
数値をそのまま使うのも、--prio-prefix のように
8 倍してレベルを足すのも、うまく行かなかった。
- --prio-prefix
-
標準入力から読み込むすべての行で sysylog の接頭辞 (prefix)
を捜す。この接頭辞は、山かぎカッコ (<>) で囲まれた 10 進数であり、
ファシリティとレベルの両方をエンコードしたものである。数値は、ファシリティを
(訳注: その数値表現を) 8 倍し、それにレベルを加えて作る。たとえば、local0.info
なら、ファシリティは 16、レベルは 6 なので <134> になる。
接頭辞がファシリティを含んでいない場合、ファシリティは、-p
オプションで指定したものがデフォルトである。
同様に、接頭辞が全く指定されていない場合、その行は、-p
で指定された優先度 priority を使ってログに記録される。
このオプションは、コマンドライン引き数として指定したメッセージに対しては働かない。
-
- [訳注]
-
別の角度から説明すると、
これは、入力するメッセージの行中でファシリティとレベルを指定する方法だと言えるだろう。
メッセージをファイル、または標準入力から入力するとき
(コマンドラインの引き数としてではない)、logger コマンドに
--prio-prefix オプションを付け、メッセージ各行の行頭には
<134> などと書いておく。そうすると、logger
がその行を優先度 local0.info
のメッセージなどと解釈して、適切なログファイルに送ってくれるのである。
<134> などの接頭辞がログに書き込まれるわけではない。
- --rfc3164
-
リモートサーバにメッセージを送るのに RFC 3164 の BSD syslog プロトコルを使用する。
- --rfc5424[=without]
-
リモートサーバにメッセージを送るのに RFC 5424 の syslog プロトコルを使用する。
指定が任意の without という引き数には、notq, notime, nohost
という値をコンマで区切ったリストが使用できる。
notq という値は、送信するメッセージに時間品質構造化データ
(the time-quality structured data) を記入しないようにする。
この時間品質情報が示すのは、ローカルクロックが
(訳注: 信用できる外部の時刻サーバとメッセージ送信時に)
同期されていたかどうか、及び、タイムスタンプが (訳注: 同期と同期の間に)
ずれるかもしれない最大のマイクロセコンド数である。
時間品質は、--sd-id timeQuality が指定された場合にも自動的に抑制される。
notime という値は (暗黙裡に notq も設定する)、ISO-8601
フォーマットの省略なしの送信側タイムスタンプを記入しないようにする。
マイクロセコンドやタイムゾーンを含むフォーマットのことである。
nohost という値は、メッセージのヘッダに gethostname(2)
の情報を入れないようにする。
-
RFC 5424 プロトコルは、バージョン 2.26 以来、logger のデフォルトになっている。
- -s, --stderr
-
メッセージをシステムログだけでなく、標準エラーにも出力する。
- --sd-id name[@digits]
-
RFC 5424 メッセージヘッダで使う構造化データ要素の識別名
(a structured data element ID)
を指定する。新しい要素を導入するには、このオプションを --sd-param
の前で使わなければならない。構造化データ要素の数には上限がない。ID
(識別名。name には @digit が続くこともある)
は、大文字小文字を区別し、要素のタイプと用途を一意に同定している。同じ
ID は、一つのメッセージに 1 回しか現れてはならない。@digit
の部分は、ユーザが定義した非標準的な ID では必須である。
現在 logger が (訳注: --rfc5424 オプションを指定したときにデフォルトで)
生成するのは、標準要素 timeQuality のみである。RFC
5424 には、そのほか origin 要素 と meta 要素が記述されている
(前者には、ip, enterpriseId, software, swVersion
といったパラメータが、後者には、sequenceId, sysUpTime, language
といったパラメータがある)。こうした要素 ID は、@digits
という接尾辞なしで指定することができる。
- --sd-param name="value"
-
構造化データ要素のパラメータを、名前と値の組み合わせで指定する。
このオプションを使うときは、--sd-id
の後ろに置かなければならない。なお、同じ要素について、2
回以上指定することもできる。value
を囲む引用符は必須であり、しかも、
コマンドライン上ではエスケープしなければならないことに注意していただきたい。
-
logger --rfc5424 --sd-id zoo@123 \
--sd-param tiger=\"hungry\" \
--sd-param zebra=\"running\" \
--sd-id manager@123 \
--sd-param onMeeting=\"yes\" \
"this is message"
-
上のコマンドは、次のようなメッセージを生成する。
-
<13>1 2015-10-01T14:07:59.168662+02:00 ws kzak - - [timeQuality tzKnown="1" isSynced="1" syncAccuracy="218616"][zoo@123 tiger="hungry" zebra="running"][manager@123 onMeeting="yes"] this is message
- -S, --size size
-
メッセージの許可される最大のサイズを size にする。デフォルトは、1KiB
の文字である。これは、昔から使われている上限であり、RFC 3167
で規定されている。なお、RFC 5424 で、この上限は融通が利くようになった。
受信側が RFC 5424 に準じているならば、少なくとも 4KiB
のメッセージを処理できると考えて、まず間違いがない。
どんなタイプの syslog プロトコルを使っていようと、たいていの受信側が
1 KiB より大きいメッセージを受け入れる。従って、この --size
オプションが (--rfc5424 を使用した場合だけではなく)
あらゆる場合に logger に対して働くことになる。
注意: メッセージサイズの上限というのは、syslog
のヘッダを含む、メッセージサイズ全体の上限である。
ヘッダのサイズは、選択したオプションやホスト名の長さによって変わってくる。
大雑把に言って、ヘッダが 50 から 80 文字 (characters)
より長いことはあまりない。メッセージの最大ザイズを選択するときは、
受信側の方でもその最大サイズをサポートするようにしておくことが重要である。
さもないと、メッセージは、尻尾がちょん切られてしまうかもしれない。
もう一度大雑把に言うと、2 から 4 KiB
のメッセージサイズなら、たいてい問題がないはずだ。
それより大きい場合は、ちゃんと動作するか確認するべきである。
- --socket-errors[=mode]
-
Unix ソケット接続に関するエラーを表示する。mode の値は、off, on,
auto の何れかである。mode が auto の場合、logger は、init
プロセスが systemd かどうか検出しようとする。そして、もしそうならば、
/dev/log がブートの早い段階から使用可能になっていると想定する。
他の init システムで、/dev/log
を欠いている場合、ここで述べているようなエラーが起きることはない。そのへんは、openlog(3)
システムコールを使用するメッセージ処理と同じことである。logger(1) も、
バージョン 2.26 より前は openlog を使用していた。そのため、Unix
ソケットに送信したメッセージが消失しても、当時は検出できなかったのである。
デフォルトの mode は、auto
である。エラー表示が有効ではないと、メッセージの消失があっても、通知されず、logger
の実行は、成功のステータスで終わることになる。
- -T, --tcp
-
ストリーム (TCP) のみを使用する。デフォルトでは、/etc/service
で定義されている syslog-conn ポートに接続が試みられる。それは、たいてい
601 番である。
接続先の指定については、--server や --socket もご覧いただきたい。
- -t, --tag tag
-
ログに記録されるすべての行に tag
という指標を付ける。デフォルトのタグは、端末にログインしているユーザの名前
(あるいは、実効ユーザ ID に基づいたユーザ名) である
- -u, --socket socket
-
システムログのソケットの代わりに、指定された socket に書き込む。
- --
-
引き数のリストの終わりを示す。これを使えば、message をハイフン (-)
で始めることができる。
- -V, --version
-
バージョン情報を表示して終了する。
- -h, --help
-
ヘルプを表示して終了する。