ipaimport - Import textual data into an IPA data store
ipaimport --catalog CATALOG_NAME --type CATALOG_TYPE --start=START_TIME] [--end=END_TIME [--description=DESCRIPTION] [--delimiter=DELIM] [--append] [--db=DB_URI] [--progress=NUM] INPUT_FILE
ipaimport reads IP addresses (and optionally values associated with those IP addresses) and imports them into an IPA catalog.
Specifies the name of the IPA catalog to import into. If the catalog does not already exist in the IPA data store, it will be created. This option is required. The '.' character in catalog names can be used to establish a catalog hierarchy, such that the foo.bar catalog is considered a child of the foo catalog. This can be useful for organizing IP data into different categories, semgenting host data by department/functional area, etc.
Selects the type of the IPA catalog to be imported into. Valid catalog types are:
An IPSet catalog. This is simply a set of IP ranges with no associated values.
A Bag (multiset) catalog. This is a set of IP ranges with associated integer values.
A prefix map catalog. This is a set of IP ranges with associated textual labels.
A multimap catalog. This is an extension of the prefix map type where ranges can have multiple labels, and each range-label pair has an associated integer value.
An optional text description of the catalog's contents. This description will be stored in the database and will be visible when querying available catalogs with the ipaquery tool.
Specifies the character used as a field delimiter in the input file. By default, ipaimport uses whitespace as the field delimiter.
Specifies the beginning of the time range for which the imported data is valid. See TIME RANGES below for more information on how time ranges are used in IPA.
Specifies the end of the time range for which the imported data is valid. See TIME RANGES below for more information on how time ranges are used in IPA.
If this switch is provided, records should be appended to an existing dataset. The time period for the dataset to be selected is specified by the --start and --end options above.
A URI specifying the IPA data store to connect to. Due to the possible exposure of database credentials via process listings, the use of this option is discouraged. See ENVIRONMENT below for the recommended way of specifying the IPA data store URI.
Print a progress marker every NUM imported records.
Datasets in an IPA catalog are assigned a time range that specifies the time during which the data is considered valid. Time ranges cannot overlap, and any attempts to import data with a time range that is already covered within the chosen catalog will produce an error.
The timestamp format for the --start and --end arguments is YYYY/MM/DD[:HH[:MM[:SS]]]. If the hours, minutes, or seconds are not specified, they are assumed to be zero (the beginning of the day, hour, or minute, respectively.)
In lieu of a timestamp, the --start and --end switches can take a special value of '...' (three dots). These represent "the beginning of time" and "the end of time" respectively, so that the time ranges can have infinite endpoints. In the case where both the --start and end switches are '...', the dataset is considered valid no matter what time period is queried.
Time ranges should be treated as left-closed, right-open intervals. This means that, whereas the --begin timestamp is part of the dataset's time range, the --end switch timestamp is not actually included in the range, but everything prior to it is. See the EXAMPLES section for further clarification.
The expected format of the input file depends on the type of the catalog. For all catalog types, "IP range" is defined as an IP address or range of addresses in any of the following formats:
single dotted quad address: 192.168.1.0
single integer address: 3232235776
dotted quad address range: 192.168.1.0-192.168.1.255
integer address range: 3232235776-3232236031
CIDR block: 192.168.1.0/24
CIDR block with int addr: 3232235776/24
For IP set catalogs, the input format is simply one IP range per line:
For Bag (multiset) catalogs, the input format is an IP range and an integer value, delimited by either whitespace or the --delimiter character:
188.8.131.52/8 100 184.108.40.206/8 30
For prefix map catalogs, the input format is an IP range and a textual label associated with that range, delimited by either whitespace or the --delimiter character:
220.127.116.11/8 foo 18.104.22.168/8 bar
For multimap catalogs, the input format is an IP range, a textual label, and an integer value, delimited by either whitespace or the --delimiter character:
22.214.171.124/8 foo 64 126.96.36.199/8 bar 1 188.8.131.52/8 foo 0 184.108.40.206/8 bar 99 220.127.116.11/8 baz 3
Note that the multimap catalog type is the only type where IP ranges can be duplicated.
To import IP set data into a "set" catalog that is valid for the month of January, 2009:
$ ipaimport --catalog testset --type set \ --start 2009/01/01 --end 2009/02/01 test.2009-01.set.in
To import the following month's data into the same catalog:
$ ipaimport --catalog testset --type set \ --start 2009/02/01 --end 2009/03/01 test.2009-02.set.in
To import Bag data for all dates prior to 2009:
$ ipaimport --catalog testbag --type bag \ --start ... --end 2009/01/01 test.bag.in
To import prefix map data for the year 2009 and beyond:
$ ipaimport --catalog testpmap --type pmap \ --start 2009/01/01 --end ... test.pmap.in
To import multimap data valid for any given time:
$ ipaimport --catalog testmmap --type mmap \ --start ... --end ... \ test.mmap.in
A URI specifying the location of (and credentials for) the IPA data store. The format of this URI is driver://user:password@hostname/database, e.g.:
Currently, only the PostgreSQL database driver is supported.
In version 0.3.0 and earlier, a syntax of a.b.c.x-y was supported for IP ranges. Support for this syntax has been dropped due to its ambiguous nature, given that we also accept integer input for addresses.