netdisco-frontend 1.0-2 / usr / share / netdisco / html / doc / netdisco-api-shared.html

<%text>

<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->

<ul>

	<li><a href="#name">NAME</a></li>
	<li><a href="#description">DESCRIPTION</a></li>
	<li><a href="#author">AUTHOR</a></li>
	<li><a href="#synopsis">SYNOPSIS</a></li>
	<li><a href="#globals">GLOBALS</a></li>
	<li><a href="#exportable_functions">Exportable Functions</a></li>
	<ul>

		<li><a href="#general_functions">General Functions</a></li>
		<li><a href="#user_functions">User Functions</a></li>
		<li><a href="#sql_functions">SQL Functions</a></li>
	</ul>

</ul>
<!-- INDEX END -->

<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>netdisco.pm - Utility functions used for back and front ends</p>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>This module provides utility functions for use with netdisco in both 
the front and backend.  Front-end specific features are limited to the
mason (.html) files, and the back-end specific features are limited to
netdisco.</p>
<p>
</p>
<hr />
<h1><a name="author">AUTHOR</a></h1>
<p>Max Baker</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<p>
</p>
<hr />
<h1><a name="globals">GLOBALS</a></h1>
<dl>
<dt><strong><a name="item__netdisco__dbh">%netdisco::DBH</a></strong>

<dd>
<p>Holds Database Handles, key is db name as set in config file.</p>
</dd>
</li>
<dt><strong><a name="item__netdisco__db">%netdisco::DB</a></strong>

<dd>
<p>Index of current Database Handle.  Default <code>'Pg'</code>;</p>
</dd>
</li>
<dt><strong><a name="item__netdisco__config">%netdisco::CONFIG</a></strong>

<dd>
<p>Holds config info from <code>netdisco.conf</code></p>
</dd>
</li>
<dt><strong><a name="item__netdisco__graph">%netdisco::GRAPH</a></strong>

<dd>
<p>Holds vertex information for <a href="#item_make_graph"><code>make_graph()</code></a></p>
</dd>
</li>
<dt><strong><a name="item__netdisco__sendmail">$netdisco::SENDMAIL</a></strong>

<dd>
<p>Full path to sendmail executable</p>
</dd>
</li>
<dt><strong><a name="item__netdisco__sqlcarp">$netdisco::SQLCARP - Carps SQL!</a></strong>

<dd>
<p>This will <code>carp()</code> the SQL sent off to the server for Debugging.</p>
</dd>
<dd>
<p>If running under mason, the output of <code>carp()</code> goes to the Apache
Error Log.  From the shell it goes to STDERR.</p>
</dd>
<dd>
<p>Note that if you set this on a MASON page, the value will remain
cached across most of the current httpd proccesses.  Make sure you set it 
back to 0 via mason when you're done, unless you like watching Apache's
error_log grow.</p>
</dd>
</li>
<dt><strong><a name="item__port_control_reasons">%PORT_CONTROL_REASONS</a></strong>

<dd>
<p>Reason why a port would be shutdown. These get fed into <code>port_control_log</code></p>
</dd>
</li>
<dt><strong><a name="item__version">$VERSION - Sync'ed with Netdisco releases</a></strong>

</dl>
<p>
</p>
<hr />
<h1><a name="exportable_functions">Exportable Functions</a></h1>
<p>
</p>
<h2><a name="general_functions">General Functions</a></h2>
<dl>
<dt><strong><a name="item_add_arp"><code>add_arp(mac,ip)</code></a></strong>

<dd>
<p>Manipulates entries in 'node_ip' table.</p>
</dd>
<dd>
<p>Expires old entries for given IP address.</p>
</dd>
<dd>
<p>Adds new entry or time stamps matching one.</p>
</dd>
</li>
<dt><strong><a name="item_add_node"><code>add_node(mac,ip,port)</code></a></strong>

<dd>
<p>Manipulates entries in <code>node</code> table.</p>
</dd>
<dd>
<p>Expires old entries matching given arguments.</p>
</dd>
<dd>
<p>Adds a new entry or time stamps matching old entry.</p>
</dd>
</li>
<dt><strong><a name="item_add_nbt"><code>add_nbt(ip,mac,nbname,domain,server,nbuser)</code></a></strong>

<dd>
<p>Manipulates entries in 'node_nbt' table.</p>
</dd>
<dd>
<p>Expires old entries for given MAC address.</p>
</dd>
<dd>
<p>Adds new entry or time stamps matching one.</p>
</dd>
</li>
<dt><strong><a name="item_bits_to_mask"><code>bits_to_mask(bits)</code></a></strong>

<dd>
<p>Takes a CIDR style network mask in number of bits (/24) and returns the older style 
bitmask.</p>
</dd>
</li>
<dt><strong><a name="item_get_community"><code>get_community(type,host,ip)</code></a></strong>

<dd>
<p>Get Community depending on type (ro,rw).
If <a href="#item_get_community"><code>get_community</code></a> is defined, then get the try to get the community from
shell-command. If <a href="#item_get_community"><code>get_community</code></a> is undefined or nothing
is returned from the command use <code>community</code> or 
<code>community_rw</code>.</p>
</dd>
<dd>
<p>The command specified in <a href="#item_get_community"><code>get_community</code></a> must return in stdout a string like</p>
</dd>
<dd>
<pre>
    community=&lt;list of readonly-communities&gt;
    setCommunity=&lt;list of write-communities&gt;</pre>
</dd>
<dd>
<p>Returns Community-List as Array reference</p>
</dd>
<dd>
<p>Options:
    type =&gt; 'ro'|'rw' for the type of community
    host =&gt; name of the device
    ip   =&gt; device ip-address</p>
</dd>
</li>
<dt><strong><a name="item_config"><code>config()</code></a></strong>

<dd>
<p>Reads the config file and fills the <code>%CONFIG</code> hash.</p>
</dd>
</li>
<dt><strong><a name="item_updateconfig"><code>updateconfig()</code></a></strong>

<dd>
<p>Checks the modification time of the configuration file and
re-reads it if needed.  (Note: for now, defaults are not
reset - i.e., if there was an item in the config file before,
and it is missing when we reread it, it keeps its old value
and doesn't get set to the default.)</p>
</dd>
<dd>
<p>Uses eval to run config, so that we can keep running with the old
config if there's a problem with the config file.</p>
</dd>
</li>
<dt><strong><a name="item_has_layer">has_layer(bit string,layer)</a></strong>

<dd>
<p>Takes ascii encoded string of eight bits, and checks for the specific
layer being true.  Most significant bit first.</p>
</dd>
<dd>
<pre>
    has_layer(00000100,3) = true</pre>
</dd>
</li>
<dt><strong><a name="item_hostname"><code>hostname(ip)</code></a></strong>

<dd>
<p>Returns the DNS server entry for the given ip or hostname.</p>
</dd>
</li>
<dt><strong><a name="item_getip"><code>getip(host)</code></a></strong>

<dd>
<p>Returns the IP Address of a given IP or hostname. If the 
given argument appears to be in dotted octet notation, it
does no DNS hits and just returns it.</p>
</dd>
<dd>
<p>It also just returns an IP address with a subnet mask.
Subnet masks are not permitted on host names.</p>
</dd>
</li>
<dt><strong><a name="item_in_device"><code>in_device(device,to_match)</code></a></strong>

<dd>
<p>First argument can either be:</p>
</dd>
<dd>
<pre>
    1. plain text IP or hostname
    2. A row from the device table as returned from sql_hash</pre>
</dd>
<dd>
<p>Second argument is an array ref as returned from config, eg. <code>bulkwalk_no</code>.</p>
</dd>
</li>
<dt><strong><a name="item_in_subnet"><code>in_subnet(subnet,ip)</code></a></strong>

<dd>
<p>Returns Boolean.  Checks to see if IP address is in subnet.  Subnet
is defined as single IP address, or CIDR block.  Partial CIDR format
(192.168/16) is NOT supported.</p>
</dd>
<dd>
<pre>
 in_subnet('192.168.0.0/24','192.168.0.3') = 1;
 in_subnet('192.168.0.3','192.168.0.3') = 1;</pre>
</dd>
</li>
<dt><strong><a name="item_in_subnets"><code>in_subnets(ip,config_directive)</code></a></strong>

<dd>
<p>Returns Boolean.  Checks a given IP address against all the IPs and subnet
blocks listed for a config file directive.</p>
</dd>
<dd>
<pre>
 print in_subnets('192.168.0.1','macsuck_no');</pre>
</dd>
</li>
<dt><strong><a name="item_active_subnets"><code>active_subnets()</code></a></strong>

<dd>
<p>Returns array ref containing all rows from the subnets table that
have a node or device in them.</p>
</dd>
</li>
<dt><strong><a name="item_dump_subnet">dump_subnet(cidr style subnet)</a></strong>

<dd>
<p>Serves you all the possible IP addresses in a subnet.</p>
</dd>
<dd>
<p>Returns reference to hash.  Keys are IP addresses
in dotted decimal that are in the subnet.</p>
</dd>
<dd>
<p>Gateway and Broadcast (.0 .255) addresses are not included.</p>
</dd>
<dd>
<pre>
  $hash_ref = dump_subnet('192.168.0.0/24');
  scalar keys %$hash_ref == 254;</pre>
</dd>
<dd>
<p>Also accepted :</p>
</dd>
<dd>
<pre>
  dump_subnet('14.0/16');
  dump_subnet('4/24');</pre>
</dd>
</li>
<dt><strong><a name="item_is_mac"><code>is_mac(mac)</code></a></strong>

<dd>
<p>Returns Boolean.  Checks if argument appears to be a mac address.</p>
</dd>
<dd>
<p>Checks for types :</p>
</dd>
<dd>
<pre>
    08002b:010203
    08002b-010203
    0800.2b01.0203
    08-00-2b-01-02-03
    08:00:2b:01:02:03</pre>
</dd>
</li>
<dt><strong><a name="item_log"><code>log(class,text)</code></a></strong>

<dd>
<p>Inserts an entry in the <a href="#item_log"><code>log</code></a> table.</p>
</dd>
<dd>
<pre>
    log('error',&quot;this is an error&quot;);</pre>
</dd>
</li>
<dt><strong><a name="item_mail"><code>mail(to,subject,body)</code></a></strong>

<dd>
<p>Sends an E-Mail as Netdisco</p>
</dd>
</li>
<dt><strong><a name="item_is_private"><code>is_private(ip)</code></a></strong>

<dd>
<p>Returns true if a given IP address is in the RFC1918 private
address range.</p>
</dd>
</li>
<dt><strong><a name="item_cidr">cidr(ip, mask)</a></strong>

<dd>
<p>Takes an IP address and netmask and returns the CIDR format
subnet.</p>
</dd>
</li>
<dt><strong><a name="item_mask_to_bits"><code>mask_to_bits(mask)</code></a></strong>

<dd>
<p>Takes a netmask and returns the CIDR integer number of bits.</p>
</dd>
<dd>
<pre>
    mask_to_bits('255.255.0.0') = 16</pre>
</dd>
</li>
<dt><strong><a name="item_is_secure">is_secure</a></strong>

<dd>
<p>To be run under mason only.</p>
</dd>
<dd>
<p>Returns true if the server want's to be secure and is, or true if the server doesn't want to be secure.</p>
</dd>
<dd>
<p>Returns false if the server is not secure but wants to be.</p>
</dd>
</li>
<dt><strong><a name="item_url_secure"><code>url_secure(url)</code></a></strong>

<dt><strong><a name="item_sort_ip"><code>sort_ip()</code></a></strong>

<dd>
<p>Used by <code>sort {}</code> calls to sort by IP octet.</p>
</dd>
<dd>
<p>If passed two hashes, will sort on the key <code>ip</code> or <code>remote_ip</code>.</p>
</dd>
</li>
<dt><strong><a name="item_sort_port"><code>sort_port()</code></a></strong>

<dd>
<p>Used by <code>sort()</code> - Sort port names with the following formatting types :</p>
</dd>
<dd>
<pre>
    A5
    5
    FastEthernet0/1
    FastEthernet0/1-atm
    5.5
    Port:3</pre>
</dd>
<dd>
<p>Works on hashes if a key named port exists.</p>
</dd>
<dd>
<p>Cheers to Bradley Baetz (bbaetz) for improvements in this sub.</p>
</dd>
</li>
<dt><strong><a name="item_make_graph"><code>make_graph()</code></a></strong>

<dd>
<p>Returns <code>Graph::Undirected</code> object that represents the discovered
network.</p>
</dd>
<dd>
<p>Graph is made by loading all the <code>device_port</code> entries
that have a neighbor, using them as edges. Then each device seen in those
entries is added as a vertex.</p>
</dd>
<dd>
<p>Nodes without topology information are not included.</p>
</dd>
</li>
<dt><strong><a name="item_root_device"><code>root_device(ip)</code></a></strong>

<dd>
<p>If the given IP Address matches a device IP, returns it.</p>
</dd>
<dd>
<p>If the given IP Address matches an alias of a device, returns
the IP of the device the alias belongs to.</p>
</dd>
</li>
</dl>
<p>
</p>
<h2><a name="user_functions">User Functions</a></h2>
<dl>
<dt><strong><a name="item_user_add"><code>user_add(user,%args)</code></a></strong>

<dd>
<p>Adds or changes a user account.</p>
</dd>
<dd>
<p><code>%args</code> can have key values of { pw, admin, port, ldap, full_name, note }</p>
</dd>
<dd>
<p>Returns error message if problem.</p>
</dd>
</li>
<dt><strong><a name="item_user_del"><code>user_del(user)</code></a></strong>

<dd>
<p>Deletes a user from netdisco.</p>
</dd>
<dd>
<p>Returns result from <code>DBI-&gt;do()</code></p>
</dd>
<dd>
<p>Integer for number of rows deleted, or undef if error.</p>
</dd>
</li>
<dt><strong><a name="item_user_ldap_verify"><code>user_ldap_verify(user,password)</code></a></strong>

<dd>
<p>Test a user from netdisco.</p>
</dd>
<dd>
<p>Returns 1 if user and password are OK, or undef if error.</p>
</dd>
</li>
<dt><strong><a name="item_ldap_search"><code>ldap_search(filter,attrs,user,pass)</code></a></strong>

<dd>
<p>Perform an LDAP search from the configured ldap_base with the specified filter.</p>
</dd>
<dd>
<p>Uses an anonymous bind if the user is 'anonymous' or undefined.</p>
</dd>
<dd>
<p>Returns reference to an array of Net::LDAP::Entry objects which match the
search filter.  Each entry will contain the accessible attributes as defined
in attrs array reference.  If attrs is undefined, then the server will return
the attributes that are specified as accessible by default given the bind
credentials.</p>
</dd>
</li>
</dl>
<p>
</p>
<h2><a name="sql_functions">SQL Functions</a></h2>
<dl>
<dt><strong><a name="item_dbh"><code>dbh()</code></a></strong>

<dd>
<p>Creates and returns a database handle. Creates once, then 
returns the cached copy.</p>
</dd>
<dd>
<p>Select database handle in use by localizing <code>$netdisco::DB</code></p>
</dd>
</li>
<dt><strong><a name="item_dbh_quote"><code>dbh_quote($text)</code></a></strong>

<dd>
<p>Runs DBI::dbh-&gt;<code>quote()</code> on the text and returns it.</p>
</dd>
</li>
<dt><strong><a name="item_hash_diff"><code>hash_diff($hashref_orig,$hashref_new)</code></a></strong>

<dd>
<p>Sees if items to change in second hash are different or new compared to first.</p>
</dd>
</li>
<dt><strong><a name="item_insert_or_update">insert_or_update(table, {matching}, {values} )</a></strong>

<dd>
<p>Checks for Existing entry in table using <code>\%matching</code> and either
updates or inserts into table with <code>\%values</code> accodringly.</p>
</dd>
<dd>
<pre>
    insert_or_update('device', { 'ip'=&gt;'127.0.0.1' },
                     { 'ip' =&gt; '127.0.0.1', dns =&gt; 'dog' }
                    );</pre>
</dd>
<dd>
<p>First time called it will insert the new entry</p>
</dd>
<dd>
<p>Second time called it will modify the entry with the values.</p>
</dd>
<dd>
<p>Supports</p>
</dd>
<dd>
<pre>
    * Auto Quoting of Values</pre>
</dd>
<dd>
<p>Returns undef if problem.</p>
</dd>
<dd>
<p>On inserts in PostgreSQL, returns the OID of the row inserted.</p>
</dd>
<dd>
<p>Or returns value from <code>DBD::St::execute()</code></p>
</dd>
</li>
<dt><strong><a name="item_sql_column"><code>sql_column(table,[key_col,val_col],{where})</code></a></strong>

<dd>
<p>Returns reference to hash.  Hash has form <code>$hash{key_val}={val_val}</code></p>
</dd>
<dd>
<p>If multiple matches are found for key_col, only the last one is kept.</p>
</dd>
<dd>
<p>Usage is the same as <a href="#item_sql_rows"><code>sql_rows()</code></a> -- See for Usage.</p>
</dd>
<dd>
<pre>
    $OldDevices = sql_column('device',['ip','layers']);</pre>
</dd>
<dd>
<p>Creates the hash %$OldDevices where the key is the IP address and the Value is the Layers</p>
</dd>
</li>
<dt><strong><a name="item_sql_columns"><code>sql_columns(table,[key_col,val_col,...],{where})</code></a></strong>

<dd>
<p>Returns reference to hash.  Hash has form <code>$hash{key_val}=hash of all columns}</code></p>
</dd>
<dd>
<p>If multiple matches are found for key_col, only the last one is kept.</p>
</dd>
<dd>
<p>Usage is the same as <a href="#item_sql_rows"><code>sql_rows()</code></a> -- See for Usage.</p>
</dd>
<dd>
<pre>
    $OldDevices = sql_columns('device',['ip','layers','dns']);</pre>
</dd>
<dd>
<p>Creates the hash %$OldDevices where the key is the IP address and the Value is a hash
with the keys 'ip', 'layers' and 'dns'.</p>
</dd>
</li>
<dt><strong><a name="item_sql_do"><code>sql_do(sql)</code></a></strong>

<dd>
<p>Simple wrapper to <code>$dbh-&gt;do()</code></p>
</dd>
<dd>
<p>No quoting.</p>
</dd>
</li>
<dt><strong><a name="item_sql_begin"><code>sql_begin()</code></a></strong>

<dd>
<p>Start an SQL transaction.</p>
</dd>
<dd>
<p>Pass an array reference to the list of tables that should be
locked in EXCLUSIVE mode for this transaction.  Normally, row
locking is sufficient, so no tables need be locked.  However,
netdisco's macsuck and arpnip processes perform statements like</p>
</dd>
<dd>
<pre>
    UPDATE table SET active='f' WHERE (ip|mac)='foo'</pre>
</dd>
<dd>
<p>If two such statements are executed concurrently for the
same value of 'foo', they can visit the same rows in different
order, resulting in a deadlock.  It's tempting to say that
you can solve this by making the UPDATE only touch one row at
a time by adding ``AND active'' to the WHERE clause; however,
it's possible to get multiple rows with active=true and open
up the window for deadlock again.  Without a significant
rewrite, the best option is to lock the appropriate table in
exclusive mode (which still allows readers, such as the web
front end, but blocks any inserts or updates).  Since netdisco
performs updates in bulk, the table will not spend a significant
amount of time locked.</p>
</dd>
</li>
<dt><strong><a name="item_sql_commit"><code>sql_commit()</code></a></strong>

<dd>
<p>Finish an SQL transaction and return to AutoCommit mode</p>
</dd>
</li>
<dt><strong><a name="item_sql_rollback"><code>sql_rollback()</code></a></strong>

<dd>
<p>If an SQL transaction is in progress, roll it back
and return to AutoCommit mode.  Suitable to be called
in a generic error situation when you don't know what
has been done, since it is a noop if there is no transaction
occurring.</p>
</dd>
</li>
<dt><strong><a name="item_sql_disconnect"><code>sql_disconnect()</code></a></strong>

<dd>
<p>Disconnect from the SQL database, e.g., before forking.</p>
</dd>
</li>
<dt><strong><a name="item_sql_hash">sql_hash(table, [columns], {where})</a></strong>

<dd>
<p>Returns reference to hash representing single row.</p>
</dd>
<dd>
<p>Usage is the same as <a href="#item_sql_rows"><code>sql_rows()</code></a> -- See for Usage.</p>
</dd>
<dd>
<pre>
    my $hashref = sql_hash('device',['ip','ports'], {'ip'=&gt;'127.0.0.1'});</pre>
</dd>
</li>
<dt><strong><a name="item_sql_match"><code>sql_match(text,exact_flag)</code></a></strong>

<dd>
<p>Parses text to substitue wildcards * and ? for % and _</p>
</dd>
<dd>
<p>Optional exact_flag specifies whether or not to search for that exact text
search or to do a *text*.</p>
</dd>
<dd>
<p>Default is non_exact.</p>
</dd>
</li>
<dt><strong><a name="item_sql_rows">sql_rows(table, [columns] , {where} ,OR, orderbystring)</a></strong>

<dd>
<p>Returns a reference to an array of hash references. Each hash reference is the
return of <code>$dbh-&gt;fetchrow_hashref</code></p>
</dd>
<dd>
<p>Supports</p>
</dd>
<dd>
<pre>
    * Joins
    * Pattern Matching
    * NULL/NOT NULL 
    * Boolean OR or AND criteria
    * Auto-Quotes all values and Override
    * IN (list) and NOT IN (list) clauses</pre>
</dd>
<dd>
<p>Pass a true value for the OR argument to join constraints in the WHERE clause by 
OR instead of AND.</p>
</dd>
<dl>
<dt><strong><a name="item_simple_query_3a">SIMPLE QUERY:</a></strong>

<dd>
<p>Select info for every device:</p>
</dd>
<dd>
<pre>
    $matches = sql_rows('device',['ip','dns','uptime]);</pre>
</dd>
</li>
<dt><strong><a name="item_disable_autoquoting_3a">DISABLE AUTOQUOTING:</a></strong>

<dd>
<p>Pass the where value as a reference:</p>
</dd>
<dd>
<pre>
    sql_rows('device d, device e',['d.ip,d.dns,e.ip,e.dns'],
            {'d.dns' =&gt; \'e.dns'});</pre>
</dd>
<dd>
<p>Creates the SQL:</p>
</dd>
<dd>
<pre>
    SELECT d.ip,d.dns,e.ip,e.dns FROM device d, device e WHERE d.dns = e.dns;</pre>
</dd>
<dd>
<p>This also leaves a security hole if the where value is coming from the outside
world because someone could stuff in <code>'dog'</code>;delete from node where true;...&gt;
as a value.   If you turn off quoting make sure the program is feeding the where
value.</p>
</dd>
</li>
<dt><strong><a name="item_disable_autoquoting_and_connector">DISABLE AUTOQUOTING AND CONNECTOR</a></strong>

<dd>
<p>Pass the where value as a double scalar reference:</p>
</dd>
<dd>
<pre>
    sql_rows('device',['*'], {'age(creation)' =&gt; \\&quot;&lt; interval '1 day'&quot;})</pre>
</dd>
<dd>
<p>Creates the sql:</p>
</dd>
<dd>
<pre>
   SELECT * FROM device WHERE age(creation) &lt; interval '1 day';</pre>
</dd>
</li>
<dt><strong><a name="item_null_values">NULL VALUES</a></strong>

<dd>
<p>Select all the devices without reverse dns entries:</p>
</dd>
<dd>
<pre>
  $matches = sql_rows('device',['ip','name'],{'dns'=&gt;'IS NULL'});</pre>
</dd>
</li>
<dt><strong><a name="item_joins">JOINS</a></strong>

<dd>
<pre>
    $matches = sql_rows('device d left join device_ip i on d.ip = i.ip',
                        ['distinct(d.ip)','d.dns','i.alias','i.ip'],
                        {'d.ip/i.alias'=&gt;'127.0.0.1', 'd.dns/i.dns' =&gt; 'dog%'},
                        1);</pre>
</dd>
<dd>
<p>Selects all rows within <code>device</code> and <code>device_ip</code> where 
<code>device_ip.alias</code> or <code>device.ip</code> are <code>localhost</code>
or <code>device_ip.dns</code> or <code>device.dns</code> has <code>dog</code> in it.</p>
</dd>
<dd>
<p>Where columns with slashes are split into separate search terms combined with <code>OR</code>:</p>
</dd>
<dd>
<pre>
   { 'd.ip/i.alias' =&gt; '127.0.0.1' }</pre>
</dd>
<dd>
<p>Creates the SQL</p>
</dd>
<dd>
<pre>
   &quot;WHERE (d.ip = '127.0.0.1' OR i.alias = '127.0.0.1')&quot;</pre>
</dd>
<dt><strong><a name="item_multiple_contstraints_on_same_column">MULTIPLE CONTSTRAINTS ON SAME COLUMN</a></strong>

<dd>
<p>Pass the where values as an array reference</p>
</dd>
<dd>
<pre>
    $matches = sql_rows('device',['ip'],{'dns' =&gt; ['cat%','-g%'] },1 );</pre>
</dd>
<dd>
<p>Creates the SQL:</p>
</dd>
<dd>
<pre>
    SELECT ip FROM device WHERE (dns like 'cat%') OR (dns like '-g%');</pre>
</dd>
</li>
<dt><strong><a name="item_in">IN (list) CLAUSE</a></strong>

<dd>
<p>Pass the value as a double array reference. Values are auto-quoted.</p>
</dd>
<dd>
<p>Single array reference is for creating multiple <code>WHERE</code> entries (see above)</p>
</dd>
<dd>
<pre>
    $matches = sql_rows('node',['mac'], {'substr(mac,1,8)' =&gt; [['00:00:00','00:00:0c']]})</pre>
</dd>
<dd>
<p>Creates the SQL:</p>
</dd>
<dd>
<pre>
    SELECT mac FROM node WHERE (substr(mac,1,8) IN ('00:00:00','00:00:0c'));</pre>
</dd>
</li>
<dt><strong>NOT IN (list)</strong>

<dd>
<p>Pass the value as a double array reference.  Prepend one of the array values with a <code>!</code></p>
</dd>
<dd>
<pre>
    $matches = sql_rows('device',['name'], {'vendor' =&gt; [['!cisco','hp']]  });</pre>
</dd>
<dd>
<p>Will find all devices that are neither cisco or hp.</p>
</dd>
</li>
<dt><strong><a name="item_order_by_clause">ORDER BY CLAUSE</a></strong>

<dd>
<pre>
    $matches = sql_rows('device',['ip','dns'], undef, undef, 'order by dns limit 10');</pre>
</dd>
</dl>
<dt><strong><a name="item_sql_query">sql_query(table, [columns] , {where} ,OR, orderbystring)</a></strong>

<dd>
<p>Returns a DBI state handle on which the SQL query has been prepare()d and
execute()d.  This function is good for large queries instead of
sql_rows(), as the whole result set does not need to be read into
memory.</p>
</dd>
<dd>
<p>Code such as</p>
</dd>
<dd>
<pre>
    my $nodes = sql_rows(...);
    foreach my $row (@$nodes) {
        ...
    }</pre>
</dd>
<dd>
<p>can be replaced by</p>
</dd>
<dd>
<pre>
    my $sth = sql_query(...);
    while (my $row = $sth-&gt;fetchrow_hashref()) {
        ...
    }</pre>
</dd>
<dd>
<p>The arguments are exactly the same as sql_rows().</p>
</dd>
</li>
<dt><strong><a name="item_sql_scalar"><code>sql_scalar(table,[column],{where})</code></a></strong>

<dd>
<p>Returns a scalar of value of first column given.</p>
</dd>
<dd>
<p>Internally calls <a href="#item_sql_hash"><code>sql_hash()</code></a> which calls <a href="#item_sql_rows"><code>sql_rows()</code></a></p>
</dd>
<dd>
<p>All arguments are passed directly to <a href="#item_sql_hash"><code>sql_hash()</code></a></p>
</dd>
<dd>
<pre>
    my $count_ip = sql_scalar('device',['COUNT(ip)'],{'name' =&gt; 'dog'});</pre>
</dd>
</li>
<dt><strong><a name="item_sql_vacuum"><code>sql_vacuum(table,%opts)</code></a></strong>

<dd>
<p>Runs a VACUUM ANALYZE if we are Postgres</p>
</dd>
<dd>
<p>Pass the table name as '' if you want to vacuum all tables.</p>
</dd>
<dd>
<p>Options:</p>
</dd>
<dd>
<pre>
    verbose =&gt; 1  (set if DEBUG)
    full    =&gt; 1</pre>
</dd>
</li>
<dt><strong><a name="item_homepath"><code>homepath(config,[default])</code></a></strong>

<dd>
<p>Return the full path of the given file as specified
in the config file by prepending $CONFIG{home} to it, if
it doesn't already start with a slash.  If no value is specified
in the config file, the default is used.</p>
</dd>
</li>
<dt><strong><a name="item_tryuse"><code>tryuse(module,%opts)</code></a></strong>

<dd>
<p>Try to use the given module.</p>
</dd>
<dd>
<p>Returns two values: success / failure, and the error message if failure.
Caches values if it's non fatal.

</p>
</dd>
<dd>
<p>Options:

</p>
</dd>
<dd>
<pre>
    ver =&gt; version of module required
    die =&gt; 1 if you want to die instead of recover yourself

</pre>
</dd>
</li>
</dl>

</%text>