cfgmaker - mrtg.cfgファイル(mrtg-2.9.22用)の生成ユーティリティ
cfgmaker [オプション] [コミュニティ名@]ルータ名 [[オプション] [コミュニティ名@]ルータ名 ...]
--ifref=nr インタフェースをインタフェース番号で参照する(デフォルト) --ifref=ip ... IPアドレスで参照する --ifref=eth ... Ethernet番号で参照する --ifref=descr ... インタフェースの記述で参照する --ifref=name ... インタフェース名で参照する --ifref=type ... インタフェースのタイプで参照する
--ifdesc=nr インタフェースをインタフェース番号で記述する(デフォルト) --ifdesc=ip ... IPアドレスで記述する --ifdesc=eth ... Ethernet番号で記述する --ifdesc=descr ... descrを使って記述する --ifdesc=name ... インタフェース名で記述する --ifdesc=alias ... インタフェースの別名で記述する --ifdesc=type ... インタフェースのタイプで記述する
--if-filter=f フィルタfを使って各インタフェースをテストし、データの収集
対象にするかどうかを決定します。fは今のところPerlで使われる
表現で、返り値を使ってインタフェースのデータ収集の可否を
決定します。
(実験的な実装のため、変更されることがあります)
--if-template=templatefile
通常のデータ収集のターゲットのエントリをtemplatefile
で指定したファイルの内容と置き換えます。このファイルは
設定ファイル中のターゲット部分を生成するようなPerl
コードが書かれていることを前提にしています。
(実験的な実装のため、変更されることがあります)
--host-template=templatefile
ホストのインタフェースに加えて、ホスト自体をtemplatefile
を使ってターゲットとして生成します。このファイルは
設定ファイル中のホスト関連のターゲット(CPU、ping応答時間
の測定など)を生成するようなPerlコードが書かれていることを
前提にしています。
(実験的な実装のため、変更されることがあります)
--global "x: a" グローバルな設定エントリを追加します
--no-down インタフェースのadminあるいはoprステータスを無視します
--show-op-down 停止してあるインタフェースも表示します
--descint 'Traffic Analysis for'(だけ)以外の方法でインタフェースを
記述します
--subdirs=format ルータ毎にサブディレクトリを分けて使うようにします。
"format"にしたがってディレクトリ名がつけられ、HOSTNAMEと
SNMPNAMEはそれらの項目の持つ値と置き換わります。例えば
--subdirs=HOSTNAME or --subdirs="HOSTNAME (SNMPNAME)"
のように指定します。
--noreversedns IPアドレスの逆引きを行わないようにします
--community=cmty デフォルトのコミュニティ名"public"を"cmty"に変更します。
--snmp-options=:[<port>][:[<tmout>][:[<retr>][:[<backoff>][:<ver>]]]]
デフォルトのSNMPオプションを続く全てのルータに適用
します。個々のフィールドは空でもかまいません。続けて
指定したルータでこのオプションを変更することもできます。
--dns-domain=domain
続くルータ名のあとに付けるドメイン名を指定します。
--nointerfaces インタフェースに関連する行を生成しないようにします。
インタフェース情報の収集は行わず、関連したテンプレート
も一切実行しません。
--interfaces インタフェースに関連する行を生成します(デフォルト)。
このオプションの主な目的は、コマンドラインの前のほうで
指定した--nointerfacesオプションを打ち消すことです。
--help 簡単なヘルプメッセージを表示します --man 詳細なドキュメントを表示します --version cfgmakerのバージョンを表示します
--output=file 出力ファイル名(デフォルトはSTDOUT)
cfgmaker はルータ等のSNMPで管理できるデバイスから収集した 情報を元にMRTGの設定ファイルを生成します。
[コミュニティ名@]ルータ名
コミュニティ名 は設定ファイルの対象となるデバイスのコミュニティ名です。 特に指定がなければデフォルトの'public'が使われます。とりあえずデバイスの コミュニティ名がわからないときはデフォルトのコミュニティ名を試してみると よいでしょう。コミュニティ名が正しくないときはデバイスは応答しません。
ルータ名 はSNMPで管理可能なデバイスのDNS名あるいはIPアドレスです。 ルータ名に続けてコロンで区切った6つまでのオプションを指定できます。 実際の指定の方法は次のようになります:
ルータ名[:[prt][:[tmout][:[retr][:[backoff][:vers]]]]]
特別に説明が必要だとすれば、最後のパラメータversでしょう。この値を'2'に すると、デバイスに対してSNMPバージョン2で問い合わせを行うようになります。 こうすればデバイスのトラフィックカウンタが64ビットのポーリングを受け付ける ようになるので、高速なインタフェースでは特に有効です(カウンタがオーバーラン することがなくなります)。コマンドラインで指定するルータの順序は設定ファイル の生成時に使われるので重要です。最初に指定したルータのための設定行はファイル の最初に現れ、それに続くルータの設定も指定した順序で現れます。
--outputと--globalを除いて、すべてのオプションはコマンドラインで 指定したすぐ後のルータにだけ有効です。コマンドラインの最初のほうで 指示したオプションが、後から別の値を使って指定し直された場合、残りの ルータに関しては新しく指定した方の値が有効になります。この方法を使えば 複数のルータをまとめて扱うことも、個別に扱うことも容易になります。
--outputと--globalにコマンドラインのどこに何回現れるかでオプション の作用が違ってくることを示してあります。
以下のExamplesに複数のルータに違うオプションを指定する方法を示します。
この問題で悲しい思いをしないために、MRTGはインタフェースを他の4つの 方法で認識できるようになっています。どれもが汎用というわけではありま せんが、最低一つくらいは使える方法があるはずです。ただし、Ethernet アドレスは複数のインタフェースで同じにしているルータもあるので注意が 必要です。
インタフェースをIPアドレスで識別するにはipを、Ethernetアドレスで 識別するにはethを、インタフェースのdescriptionで識別するには descrを、インタフェース名で識別するにはnameを使います。
選んだ方法でインタフェースがユニークに識別できない場合は、cfgmakerが その旨知らせてくれます。
Title[]プロパティとHTMLコードで定義したテキストヘッダ にPageTopとして現れます。デフォルトでは単なるインタフェース番号のnrを
使うようになっていますが、これはグラフを見る側にはあまり便利とは言えません。
その他に使えるプロパティは6つあります。インタフェースのIPアドレスを使う
にはipを、Ethernetアドレスならeth、もっと記述性のよいものを使いたい ならばdescr、name、aliasがいいでしょう。機器によってこれらは
異なっているので、試行錯誤が必要になるかも知れません。例えばIOSを使って
いるCiscoルータではnameを使うと"S0"がインタフェースのdescription として返され、descrを使うと"Serial0"が、aliasには"Link to HQ"
(ルータの設定でインタフェースのdescriptionにこのように入力してあるとして) のような応答が返って来ます。
最後に、もしインタフェースをそのtype(例:"ethernetCSMA"、
"propPointtoPoin"等)で記述したいなら、typeを使います。 これは上の--descintオプションとほぼ同じです。
設定に含まれるインタフェースをより細かく指定する必要があるときに使用してください。 filter-expressionはPerlコードとして評価され、返り値が出力されることが 期待されます。これが真であればそのインタフェースは対象になり、偽であれば 外されます。
このフィルタがどのように作用するかはフィルタの詳細で後述します。
各ターゲットのための行が設定ファイルの中でどう記述されるかを指定するときに 使います。template-fileの内容は、特定の変数を入力と出力にもつPerl プログラムとして評価されます。
このテンプレートがどのように作用するかはテンプレートの詳細で後述します。
CPU使用率、ping応答時間、使用中のモデムの数など、ホストに関連した ターゲットをいくつか余計に取りたい場合に使います。template-fileの内容 はホスト毎に評価され、特定の変数を入力と出力に持つような行を生成する Perlプログラムです。
このテンプレートがどのように作用するかはテンプレートの詳細で後述します。
router[:[port][:[timeout][:[retries][:[backoff][:version]]]]]
--global "workdir: /home/mrtg"
デフォルトのオプションが必要なときは次のようにします。
--global "options[_]: growright,bits"
コマンドラインの最後のルータの後ろに--globalを指定すると、設定ファイル の最後のルータの設定部分の後ろにこの行が現れます。
cfgmaker --subdirs=HOSTNAME__SNMPNAME public@10.10.0.18
生成される行は以下のようになるはずです:
Directory[10.10.0.18_1]: 10.10.0.18__fp2200-bothrip-1.3
STDOUTです。--outputコマンドライン中で使われるのは一回だけです。 複数回指定したときは最後の--outputで指定したファイルが使われます。
このオプションを使うとcfgmakerはインタフェースに関連したステップをすべて スキップします。すなわちルータからのあらゆる情報収集を行わない設定です。 インタフェースのテンプレートも一切チェックせず、cfgmakerの実行速度を あげるために有効なオプションです。
コマンドラインで先に使用した--nointerfacesオプションを否定するための オプションです。
フィルタを使う目的はどのインタフェースを対象にする・しないを決めること にあります。各インタフェースについてこの決定は行われ、Perlコードとその 評価結果を判定するという方法をとります。結果が真であればそのインタフェース は対象になり、偽であれば対象から外されます。
フィルタを使うときに注意しなければいけないのは、空文字列``''と文字列``0'' は偽をあらわし、それ以外の全ての文字列は真とみなされることです。これは値を 0に持つ任意の整数値は未定義の値と同様、偽として扱われる こと、参照値はすべて真とみなされるということを意味します。
フィルタはPerlの表現を使って評価されるので、Perlの構造のいくつかを便利に 使うことができます:
括弧``()''を使って表現をグループ化できます。例えば次のような表現とブール 演算子の組合せが可能です:
(これ以上の詳細はPerlの本を読んだほうがいいでしょう)
フィルタに使うのに便利な定義済みの値が多数用意してあるので、ここで紹介 します。これらの値はテンプレートを使ってインタフェースを評価するときにも 使えます(ホストのテンプレートには使えません)。
警告: 変数の名前はすべて$記号で始まります。これはPerlのスカラ変数に関する 文法上の仕様です。危険なのは、$記号は多くのシェルで使用される文字(Perlの 変数同様、シェル変数として使われる)であることです。したがって、Perlの表現 がコマンドラインのシェルに渡されて評価されてしまったり、cfgmakerにコマンド ラインとして渡されてしまったりしないように注意しなければなりません。Bourne シェル、ksh、bashのようなシェルでは、表現の全体をシングルクォートで囲む ことでこのような誤った評価の実行を避けることができます:
'--if-filter=($default_iftype && $if_admin)'
よく使われるインタフェースタイプとその値は次のとおりです:
6 CSMA/CD Ethernet (ethernetCsmacd) 7 ISO88023 CSMA/CD (iso88023Csmacd) 9 ISO88025 トークンリング (iso88025TokenRing) 15 FDDI (fddi) 19 E1 20 ISDN BRI (basicISDN) 21 ISDN PRI (primaryISDN) 22 propPointToPointSerial 23 PPP (ppp) 24 ソフトウェアループバック (softwareLoopback) 30 DS3 (ds3) 32 フレームリレー (frame-relay) 33 RS232 (rs232) 37 ATM (atm) 39 SONET (sonet) 44 フレームリレーサービス (frameRelayService) 46 HSSI (hssi) 49 AAL5 (aal5) 53 propVirtual 62 Fast Ethernet (100BaseT) 63 ISDN & X.25 69 全二重 Fast Ethernet (100BaseFX) 94 Asymetric Digital Subscriber Loop (ADSL) 117 ギガビット Ethernet 9Gigabit Ethernet) 134 ATMサブインタフェース (ATM Sub Interface)
インタフェースがあるカテゴリに含まれるかどうかを簡単に判断できるように、 定義済みの値がいろいろ使えます。以下にそれらの値と対応するif_typeの番号 をリストします。他の変数を参照している変数もあるので気を付けてください。
以上に付け加えておくと、cfgmakerで使える変数はたとえそれが推奨されない方法でも すべてスクリプトから自由に操作が行えます。従って、将来さらに別のかたちで 変数や関数を使ってショートカットが使えるようになる可能性もあります。
次のフィルタはインタフェースの指定の有無にかかわらずcfgmakerに通常の動作を させます。
'--if-filter=$default'
次のフィルタを使うとcfgmakerはPPP(23)インタフェースを除外します:
'--if-filter=$default && $if_type!=23'
次のフィルタを使うとcfgmakerは通常の動作をしますが、唯一異なる点は インタフェースの運用(operational)状態を無視しつつ、固定的(administratively)に down状態のインタフェースを受け付けないということです。
'--if-filter=$if_admin && $default_iftype'
テンプレートファイルの内容はPerlプログラムとして評価されます。数値あるいは Perl変数はプログラムで読み込むことができ、その他は設定ファイルへの書き込みの 用途に使われます。
定義済みの値はほとんどがHTMLコードで使われるものとは異なりますが、いくつかは HTMLエスケープが必要です。例えば$html_syslocationは$syslocationをHTML エスケープしたものです。HTMLエスケープとは文字列``<''、``>''および``&''がそれぞれ ``<''、``>''および``&''に置き換えられるということで、文字列に埋め込まれた 改行記号は``<BR>''と空白を付け加えた(改行記号が文字列の最後に来ている場合は なにもしません)ものに置き換えられます。
これは設定行を保存するために使う変数です。テンプレートの評価の前に初期化 されるものもありますが、通常それらは最終的な設定ファイルのコメント部分 などで、テンプレートのコード中では空の文字列にしてコメントは取り去ること になるでしょう。反対に、デバッグなどの目的で変数の内容を拡張することも ありえます。
一旦テンプレートが評価されると、なにが起こるでしょうか。もしそれが インタフェースのテンプレートで、実際のインタフェースが何らかの理由で 除外されていたら、この部分はコメントアウトしなければなりません。 変数 $target_lines 中の行はすべて先頭にハッシュ記号(``#'')を付けること でコメントに変換されます。つぎにすべての変数$head_lines、$problem_lines、$target_lines および $separator_linesが連結され、設定ファイル に追加される行としてできあがります。
$problem_linesをテストすることで、あるインタフェースが設定に含まれるか 否かを調べることは可能ですが、あまり勧められません。必要であれば 代わりに$if_okを使用してください。
以下の変数はすべてインタフェースのテンプレートに使用できます。ホストの テンプレートに関しては、ホストおよびシステムの変数にあるもののみが使用 可能です。
インタフェースのテンプレートについては、さらに定義済みのフィルタ変数 にあるものも使用できます。
cfgmakerはデフォルトで各ターゲットに対して次の指定を生成します: Target[], SetEnv[], MaxBytes[], Title[], PageTop[] およびディレクトリの 指定がある場合はDirectory[]も。
デフォルトとほぼ同じターゲットの設定を生成するようなテンプレートの作成 に便利なように、上記の指示行にはそれぞれcfgmakerがデフォルトで出力する 内容を持つ変数が用意されています。
これらの変数は一切HTMLエスケープを持たないので、内包されるテキストは 必要に応じてHTMLエスケープするものとします。また、行の最後に改行は 入りません。
Name、 Description そして Alias をこのコンテキストで同時に扱うのは 紛らわしいかも知れませんし、ある程度紛らわしいのも事実です。Nameと Descriptionはほとんどの機器でサポートしていますが、どのように使うかは ベンダーや機器のカテゴリごとにさまざまです。Aliasは少なくともCiscoのIOS ではサポートされていて、変数にはIOSの設定でインタフェースの``description'' にあたる部分の内容が格納されます(SNMPの変数Descriptionと混同しない ようにしてください)。
コマンドラインからの制御をしやすくするには、$if_title_descを使うのも 手です。これはコマンドラインオプション--if-descrで制御されています。
$if_titleは$if_title_descに依存しているので、コマンドラインオプション --if-descrを使って間接的に$if_titleを操作することもできます。
(HTMLエスケープの対象になります: $html_if_title)
$if_title_descはコマンドラインオプション--if-descrを使って$if_title 同様、間接的に操作することができます。
(HTMLエスケープの対象になります: $html_if_title_desc)
ホストとインタフェースのテンプレートを書くときに便利なように以下のような 機能が提供されています。
このテンプレートファイルはインタフェース毎に設定コードを生成するという 点ではcfgmakerのデフォルトの動作と同じですが、インタフェースが受け付けられ なかった場合にその行を取り除く(設定コード、コメントの両方とも)という違い があります。
if(not $problem_lines)
{
$target_lines .= <<ECHO;
Target[$target_name]: $if_ref:$router_connect
SetEnv[$target_name]: MRTG_INT_IP="$if_ip" MRTG_INT_DESCR="$if_snmp_descr"
ECHO
if ($directory_name) {
$target_lines .= "Directory[$target_name]: $directory_name\n";
}
$target_lines .= <<ECHO;
MaxBytes[$target_name]: $if_speed
Title[$target_name]: $html_desc_prefix$html_if_title_desc -- $sysname
PageTop[$target_name]: <H1>$html_desc_prefix$html_if_title_desc -- $sysname</H1>
<TABLE>
<TR><TD>System:</TD> <TD>$sysname in $html_syslocation</TD></TR>
<TR><TD>Maintainer:</TD> <TD>$html_syscontact</TD></TR>
<TR><TD>Description:</TD><TD>$html_if_description</TD></TR>
<TR><TD>ifType:</TD> <TD>$html_if_type_desc ($if_type_num)</TD></TR>
<TR><TD>ifName:</TD> <TD>$html_if_snmp_name</TD></TR>
ECHO
$target_lines .= <<ECHO if defined $if_port_name;
<TR><TD>Port Name:</TD> <TD>$if_port_name</TD></TR>
ECHO
$target_lines .= <<ECHO;
<TR><TD>Max Speed:</TD> <TD>$if_speed_str</TD></TR>
ECHO
$target_lines .= <<ECHO if $if_ip;
<TR><TD>Ip:</TD> <TD>$if_ip ($if_dns_name)</TD></TR>
ECHO
$target_lines .= <<ECHO;
</TABLE>
ECHO
} else {
$head_lines="";
$problem_lines="";
$target_lines="";
$separator_lines="";
}
例 1 はインタフェースのターゲットの生成をどのようにカスタマイズするかの デモンストレーションと同時に``default''テンプレートで変数がどう使われるか、 すなわちcfgmakerの通常の動作の理解の助けとなるように意図したものでもあります。
もし最も簡単な方法で受け付けられなかったインタフェースに関連する行を取り除く ことだけが目的なら、<$default_target_lines>を使った下記のテンプレートで 十分です。
if($if_ok) {
$target_lines = $default_target_lines;
} else {
$head_lines="";
$problem_lines="";
$target_lines="";
$separator_lines="";
}
=head3 テンプレートの例 3: ホストのためのCPUターゲットの作成
下記にホストのテンプレートの例を示します。
$head_lines .= <<ECHO; #--------------------------------------------------------------------- ECHO
my $target_name = $router_name . ".cpu";
$target_lines .= <<ECHO;
YLegend[$target_name]: Percentage CPU load
ShortLegend[$target_name]: %
Legend1[$target_name]: CPU load in %
Legend2[$target_name]:
Legend3[$target_name]: Max Observed CPU load
Legend4[$target_name]:
LegendI[$target_name]: CPU Load:
LegendO[$target_name]:
WithPeak[$target_name]: ywm
MaxBytes[$target_name]: 100
Options[$target_name]: growright, gauge, nopercent
Title[$target_name]: $router_name CPU load
Target[$target_name]: 1.3.6.1.4.1.9.2.1.58.0&1.3.6.1.4.1.9.2.1.58.0:$router_connect
PageTop[$target_name]: <H1>$router_name CPU load</H1>
<TABLE>
<TR><TD>System:</TD><TD>$router_name in $html_syslocation</TD></TR>
<TR><TD>Maintainer:</TD><TD>$html_syscontact</TD></TR>
<TR><TD VALIGN="top">Description:</TD><TD>$html_sysdescr</TD></TR>
<TR><TD>Resource:</TD><TD>CPU.</TD></TR>
</TABLE>
ECHO
最初の例はrouter.place.xyzの設定ファイルを作成します: ルータのコミュニティ名はpublicです。インタフェースはそれぞれのIPアドレスで 識別されます。二つのグローバルオプションが設定ファイルに追加されていて、 設定ファイルはmrtg.confにリダイレクトされます。行末の``\''はこのコマンドが 単一の行に書かれなければいけないことを意味します。
cfgmaker --global "WorkDir: /home/tobi" \
--global "Options[_]: growright,bits" \
--ifref=ip \
public@router.place.xyz > mrtg.cfg
もしcfgmaker がPATHになくても、cfgmakerがカレントディレクトリに ある場合には ./cfgmaker で起動できます。
次の例は4つのデバイスに関する設定ファイルを作成します: デバイスはrouter1.place.xyz, router2.place.xyz, switch1.place.xyz およびswitch2.place.xyzで、コミュニティ名はすべて publicです。
2つのルータは--ifrefを descr に設定する一方、2つのスイッチについては --ifref を nameに設定します。さらに、ルータの --ifdesc は alias に設定し、スイッチ switch1.place.xyz は--ifdesc を descrに、 スイッチ switch2.place.xyz はそこに name を代わりに設定します。
最後に、設定中に2箇所(global)オプション行が挿入されます: 一つは最初の部分、もう一つは2つのルータの関連行の後で、かつスイッチの 関連行の前です。
cfgmaker --global "WorkDir: /home/tobi" \
--global "Options[_]: growright,bits" \
--ifref=descr \
--ifdesc=alias \
public@router1.place.xyz \
public@router2.place.xyz \
--global "Options[_]: growright" \
--ifref=name \
--ifdesc=descr \
public@switch1.place.xyz \
--ifdesc=name \
public@switch2.place.xyz > mrtg.cfg
次は --community,--snmp-options および --dns-domainを使って コマンドラインをシンプルにする方法です。PPPサーバがコミュニティ名に accessを使うのを除いてすべての機器はコミュニティ名に hiddenを 使用します。すべての機器に以下のSNMPオプションを適用します: 1s timeout, 1 retry および SNMP version 2 (backoff と port は無指定すなわちデフォルト値を使います)。ただしここでも PPPサーバは例外とし、 SNMP version 1を使います。最後にすべての機器は ドメインplace.xyzに属していますが、PPPサーバだけはドメイン remote.place.xyzに所属します。最後のPPPサーバの記述は単純に ppp-server.remoteとできる点に注目してください。
cfgmaker --global "WorkDir: /home/tobi" \
--global "Options[_]: growright,bits" \
--dns-domain=place.xyz \
--community=hidden \
--snmp-options=::1:1::2 \
router1 \
router2 \
router3 \
router4 \
router5 \
switch1 \
switch2 \
switch3 \
switch4 \
switch5 \
switch6 \
switch7 \
access@ppp-server.remote:::::1 > mrtg.cfg
Tobias Oetiker <tobi@oetiker.ch> と Jakob Ilves <jakob.ilves@oracle.com>
渡辺 知夫 <ej2@mrtg.jp>
GNU General Public License
cfgmaker is Copyright 2000 by Tobias Oetiker <tobi@oetiker.ch>