Templated Input

dug allows users to specify the format of server data provided to it.

Default Server Format#

When dug reads server data from ~/.dug/servers.csv it expects it to have a certain structure. This is also the format that is expected when either run or update use the (-f, --file) option.

That structure is as follows:


Here is some more info on the fields:

FieldPossible Values
ip_address (required)Any parseable IP (like
country_codeISO 3166-1 alpha country codes (info)
dnssectrue or false
reliabilityAny value in [0.0 - 1.0]

A valid file using the default format might look like:


Custom Input Templating#

The relevant options for templating input are --data-columns, --data-headers-present, and --data-separator and are present on both run and update. While their application on each verb is slightly different, their goal is the same: to tell dug the structure of the server data being provided to it. The notable difference is that on update they apply to servers provided via a file (-f) or a remote url (--update-url) whereas run doesnt have a remote url source specifier.

dug will allow the user to specify a file source (-f, --file) and will use it if it is in the default format. For example dug run -f ~/.dug/servers.csv will be fine. Once the user specifies a remote source (--update-url) or a file that is in another format, they will need to provide more information about the data.

More detailed descriptions of the input templating options can be found on the run and update verb pages, but heres some generalized info on them.

OptionDescriptionPossible Values
--data-columnsSpecify the fields, and their order, of the server data. Applies to data from a file (-f)(run or update) or remotely (--update-url)(update only).Any of the following (or multiple separated by commas): ipaddress, countrycode, city, dnssec, reliability, ignore
--data-headers-presentSpecifies whether or not headers are present on the server data. Can only be used in conjuction with --data-columns
--data-separatorSpecifies the separator to be used when parsing server data. Can only be used in conjuction with --data-columns.,Any character

Custom Import Templating Example#

Consider the following file named custom_headers_server.csv:

Lake Saint Louis,,US,True,1,blue

Its headers are as follows: city,ipaddress,countrycode,dnssec,reliability,color

Notice the last column, color. dug does not understand what a color field is, so this data should be ignored, that is the purpose of the ignore type in --data-columns

We could have dug understand, and use exclusively these servers for a run, with the following: dug run -f ./custom_header_servers.csv --data-headers-present --data-columns city,ipaddress,countrycode,dnssec,reliability,ignore git.kaijucode.com

Note that the above command tells us what data is in each column, and that the file's first line is headers and ought to be skipped.

If, for example, the above file used ; instead of , as the column separator you could add --data-separator ; to the previous command and have it succeed.

--data-columns Parseable Types#

The fields specified in --data-columns must be parseable from the specified source for dug to use them. Any of the provided columns, except ipaddress, can be missing and will be ignored.

Here is more info on what values can live in what columns.

FieldPossible Values
ipaddressAny parseable IP (like
countrycodeISO 3166-1 alpha country codes (info)
dnssectrue or 1 or false or 0
reliabilityAny value in [0.0 - 1.0]
ignoreAnything, its not parsed