Skip to content

Commit

Permalink
add document (#15)
Browse files Browse the repository at this point in the history
  • Loading branch information
@sjzar
sjzar authored Nov 4, 2023
1 parent 79e28e4 commit cf62af8
Show file tree
Hide file tree
Showing 30 changed files with 2,060 additions and 106 deletions.
19 changes: 18 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,21 @@ ips 是一个命令行工具与库，可以轻松完成 IP 地理位置数据库
go install github.com/sjzar/ips@latest
```

#### 二进制安装

[![Windows](https://img.shields.io/badge/-Windows_x64-blue.svg?style=for-the-badge&logo=windows)](https://github.com/sjzar/ips/releases/latest/download/ips_windows.exe)
[![Unix](https://img.shields.io/badge/-Linux/BSD-red.svg?style=for-the-badge&logo=linux)](https://github.com/sjzar/ips/releases/latest/download/ips_linux)
[![MacOS](https://img.shields.io/badge/-MacOS-lightblue.svg?style=for-the-badge&logo=apple)](https://github.com/sjzar/ips/releases/latest/download/ips_macos)

从 [GitHub Releases](https://github.com/sjzar/ips/releases) 下载最新版本的二进制文件。

#### Homebrew 安装

```bash
brew tap sjzar/tap
brew install ips
```

### 特性

* 一键查询、转存和打包 IP 地理位置数据库
Expand All @@ -30,7 +45,7 @@ go install github.com/sjzar/ips@latest

| 数据库 | 查询 | 转存 | 打包 | 官方网站 | 说明 |
|:----------|:---|:---|:---|:--------------------------------------------------|:----------|
| txt | - | ✅ | ✅ | - | 本项目转存时使用 |
| txt | ✅ | ✅ | ✅ | - | 本项目转存时使用 |
| ipdb | ✅ | ✅ | ✅ | [Link](https://ipip.net) | |
| mmdb | ✅ | ✅ | ✅ | [Link](https://maxmind.com) | |
| awdb | ✅ | ✅ | - | [Link](https://ipplus360.com) | |
Expand All @@ -40,6 +55,8 @@ go install github.com/sjzar/ips@latest

### 使用方法

更详细的使用说明请翻阅 [usage.md](./docs/usage.md) 。

#### 查询

```shell
Expand Down
35 changes: 26 additions & 9 deletions README_en.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,21 @@ ips is a command-line tool and library that facilitates the querying, dumping, a
go install github.com/sjzar/ips@latest
```

#### Binary Installation

[![Windows](https://img.shields.io/badge/-Windows_x64-blue.svg?style=for-the-badge&logo=windows)](https://github.com/sjzar/ips/releases/latest/download/ips_windows.exe)
[![Unix](https://img.shields.io/badge/-Linux/BSD-red.svg?style=for-the-badge&logo=linux)](https://github.com/sjzar/ips/releases/latest/download/ips_linux)
[![MacOS](https://img.shields.io/badge/-MacOS-lightblue.svg?style=for-the-badge&logo=apple)](https://github.com/sjzar/ips/releases/latest/download/ips_macos)

Download the latest binary files from [GitHub Releases](https://github.com/sjzar/ips/releases).

#### Homebrew Installation

```shell
brew tap sjzar/tap
brew install ips
```

### Features

* One-click querying, dumping, and packaging of IP geolocation databases
Expand All @@ -28,18 +43,20 @@ go install github.com/sjzar/ips@latest

### Supported Databases

| Database | Query | Dump | Pack | Official Website | Command |
|:----------|:---|:---|:---|:--------------------------------------------------|:----------|
| txt | - | ✅ | ✅ | - | Used for project dumps |
| ipdb | ✅ | ✅ | ✅ | [Link](https://ipip.net) | |
| mmdb | ✅ | ✅ | ✅ | [Link](https://maxmind.com) | |
| awdb | ✅ | ✅ | - | [Link](https://ipplus360.com) | |
| qqwry | ✅ | ✅ | - | [Link](https://cz88.net) | IPv4 only |
| zxinc | ✅ | ✅ | - | [Link](https://ip.zxinc.org) | IPv6 only |
| ip2region | ✅ | ✅ | - | [Link](https://github.com/lionsoul2014/ip2region) | IPv4 only |
| Database | Query | Dump | Pack | Official Website | Command |
|:----------|:------|:-----|:-----|:--------------------------------------------------|:-----------------------|
| txt | ✅ | ✅ | ✅ | - | Used for project dumps |
| ipdb | ✅ | ✅ | ✅ | [Link](https://ipip.net) | |
| mmdb | ✅ | ✅ | ✅ | [Link](https://maxmind.com) | |
| awdb | ✅ | ✅ | - | [Link](https://ipplus360.com) | |
| qqwry | ✅ | ✅ | - | [Link](https://cz88.net) | IPv4 only |
| zxinc | ✅ | ✅ | - | [Link](https://ip.zxinc.org) | IPv6 only |
| ip2region | ✅ | ✅ | - | [Link](https://github.com/lionsoul2014/ip2region) | IPv4 only |

### Usage

For more detailed usage instructions, please refer to [usage_en.md](./docs/usage_en.md).

#### Query

```shell
Expand Down
35 changes: 20 additions & 15 deletions cmd/ips/cmd_config.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,26 +37,31 @@ func init() {

var configCmd = &cobra.Command{
Use: "config [set <key> <value>] [unset <key>] [reset]",
Short: "View or modify ips configuration items",
Long: `Example:
# set ipv4 database file path
ips config set ipv4 ~/path/to/ipv4.db
Short: "Manage IPS configuration settings",
Long: `The 'ips config' command allows you to view and change various settings for IPS.
# set ipv4 database format
ips config set ipv4_format ipdb
You can specify database file paths, select output fields, and choose the format for IP databases.
# set query fields
ips config set fields "country,province,city,isp"
Use 'set' to change a setting, 'unset' to remove it, and 'reset' to revert all settings to default values.
# unset ipv6 database file path
ips config unset ipv6
For IPv6, use similar commands, like 'ips config set ipv6_format mmdb' to specify the format.
# reset config
ips config reset
For more detailed information and advanced configuration options, please refer to https://github.com/sjzar/ips/blob/main/docs/config.md
`,
Example: ` # Set the IPv4 database file path:
ips config set ipv4 ~/path/to/ipv4.db
# ipv4 format: ipip, qqwry, maxmind, ip2region, dbip
# ipv6 format: zxinc, maxmind, dbip
# use 'ips config set ipv4 ipdb' or 'ips config set ipv6 zxinc' to set format`,
# Set the IPv4 database format:
ips config set ipv4_format ipdb
# Configure the fields to display in query results:
ips config set fields "country,province,city,isp"
# Remove the IPv6 database file path setting:
ips config unset ipv6
# Reset all configuration settings to their default values:
ips config reset`,
PreRun: PreRunInit,
Run: Config,
}
Expand Down
21 changes: 12 additions & 9 deletions cmd/ips/cmd_download.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,17 +31,20 @@ func init() {
}

var downloadCmd = &cobra.Command{
Use: "download [file] [url]",
Short: "Download database files",
Long: `Example:
# download list file city.free.ipdb
ips download city.free.ipdb
Use: "download [database_name] [custom_url]",
Short: "Download IP database files",
Long: `The 'ips download' command facilitates the acquisition and updating of IP geolocation database files.
# download another database file
ips download city.ipdb https://foo.com/city.ipdb
For more detailed information and advanced configuration options, please refer to https://github.com/sjzar/ips/blob/main/docs/download.md
`,
Example: ` # To download a predefined database file
ips download city.free.ipdb
# set database file after download
ips config set ipv4 city.ipdb`,
# To download a database file from a custom URL
ips download city.ipdb https://foo.com/city.ipdb
# To configure the downloaded file as the default IPv4 database
ips config set ipv4 city.ipdb`,
PreRun: PreRunInit,
Run: Download,
}
Expand Down
26 changes: 15 additions & 11 deletions cmd/ips/cmd_dump.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,26 +27,30 @@ func init() {
rootCmd.AddCommand(dumpCmd)

// operate
dumpCmd.Flags().StringVarP(&dpFields, "fields", "f", "", "Specify the fields to be dumped from the input file. Default is all fields.")
dumpCmd.Flags().StringVarP(&dpRewriterFiles, "rewrite-files", "r", "", "List of files that need to be rewritten based on the given configurations.")
dumpCmd.Flags().StringVarP(&lang, "lang", "", "", "Set the language for the output. Example values: en, zh-CN, etc.")
dumpCmd.Flags().StringVarP(&dpFields, "fields", "f", "", UsageDPFields)
dumpCmd.Flags().StringVarP(&dpRewriterFiles, "rewrite-files", "r", "", UsageRewriteFiles)
dumpCmd.Flags().StringVarP(&lang, "lang", "", "", UsageLang)

// input & output
dumpCmd.Flags().StringVarP(&inputFile, "input-file", "i", "", "Path to the IP database file.")
dumpCmd.Flags().StringVarP(&inputFormat, "input-format", "", "", "Specify the format of the input file. Examples: ipdb, mmdb, etc.")
dumpCmd.Flags().StringVarP(&readerOption, "input-option", "", "", "Specify the option for database reader.")
dumpCmd.Flags().StringVarP(&outputFile, "output-file", "o", "", "Path to the dumped file.")
dumpCmd.Flags().StringVarP(&inputFile, "input-file", "i", "", UsageDPInputFile)
dumpCmd.Flags().StringVarP(&inputFormat, "input-format", "", "", UsageDPInputFormat)
dumpCmd.Flags().StringVarP(&readerOption, "input-option", "", "", UsageReaderOption)
dumpCmd.Flags().StringVarP(&outputFile, "output-file", "o", "", UsageDumpOutputFile)

}

var dumpCmd = &cobra.Command{
Use: "dump -i inputFile [--input-format] [-o outputFile]",
Short: "Dump data from IP database file to plain file.",
Long: `Dump data from IP database file to plain file.
Short: "Export IP database contents to a text file",
Long: `Use the 'ips dump' command to extract and export data from IP databases into a plain text format, which can be tailored by specifying fields, formats, and languages.
Example:
ips dump -i geoip.mmdb -o geoip.txt
For more detailed information and advanced configuration options, please refer to https://github.com/sjzar/ips/blob/main/docs/dump.md
`,
Example: ` # Export all fields from an IP database file to a text file
ips dump -i geoip.mmdb -o geoip.txt
# Export specific fields (country and city) from an IP database file
ips dump -i geoip.mmdb -o geoip.txt --fields "country,city"`,
PreRun: PreRunInit,
Run: Dump,
}
Expand Down
34 changes: 17 additions & 17 deletions cmd/ips/cmd_myip.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,32 +31,32 @@ func init() {
myipCmd.Flags().IntVarP(&myIPTimeoutS, "timeout", "", 0, "Set the maximum wait time for detectors.")

// operate
myipCmd.Flags().StringVarP(&fields, "fields", "f", "", "Specify the fields of interest for the IP data. Separate multiple fields with commas.")
myipCmd.Flags().BoolVarP(&useDBFields, "use-db-fields", "", false, "Use field names as they appear in the database. Default is common field names.")
myipCmd.Flags().StringVarP(&rewriteFiles, "rewrite-files", "r", "", "List of files that need to be rewritten based on the given configurations.")
myipCmd.Flags().StringVarP(&lang, "lang", "", "", "Set the language for the output. Example values: en, zh-CN, etc.")
myipCmd.Flags().StringVarP(&fields, "fields", "f", "", UsageFields)
myipCmd.Flags().BoolVarP(&useDBFields, "use-db-fields", "", false, UsageUseDBFields)
myipCmd.Flags().StringVarP(&rewriteFiles, "rewrite-files", "r", "", UsageRewriteFiles)
myipCmd.Flags().StringVarP(&lang, "lang", "", "", UsageLang)

// database
myipCmd.Flags().StringVarP(&rootFile, "file", "i", "", "Path to the IPv4 and IPv6 database file.")
myipCmd.Flags().StringVarP(&rootFormat, "format", "", "", "Specify the format of the database. Examples: ipdb, mmdb, etc.")
myipCmd.Flags().StringVarP(&rootIPv4File, "ipv4-file", "", "", "Path to the IPv4 database file.")
myipCmd.Flags().StringVarP(&rootIPv4Format, "ipv4-format", "", "", "Specify the format for IPv4 data. Examples: ipdb, mmdb, etc.")
myipCmd.Flags().StringVarP(&rootIPv6File, "ipv6-file", "", "", "Path to the IPv6 database file.")
myipCmd.Flags().StringVarP(&rootIPv6Format, "ipv6-format", "", "", "Specify the format for IPv6 data. Examples: ipdb, mmdb, etc.")
myipCmd.Flags().StringVarP(&readerOption, "database-option", "", "", "Specify the option for database reader.")
myipCmd.Flags().StringVarP(&rootFile, "file", "i", "", UsageQueryFile)
myipCmd.Flags().StringVarP(&rootFormat, "format", "", "", UsageQueryFormat)
myipCmd.Flags().StringVarP(&rootIPv4File, "ipv4-file", "", "", UsageQueryIPv4File)
myipCmd.Flags().StringVarP(&rootIPv4Format, "ipv4-format", "", "", UsageQueryIPv4Format)
myipCmd.Flags().StringVarP(&rootIPv6File, "ipv6-file", "", "", UsageQueryIPv6File)
myipCmd.Flags().StringVarP(&rootIPv6Format, "ipv6-format", "", "", UsageQueryIPv6Format)
myipCmd.Flags().StringVarP(&readerOption, "database-option", "", "", UsageReaderOption)

// output
myipCmd.Flags().StringVarP(&rootTextFormat, "text-format", "", "", "Specify the desired format for text output. It supports %origin and %values parameters.")
myipCmd.Flags().StringVarP(&rootTextValuesSep, "text-values-sep", "", "", "Specify the separator for values in text output. (default is space)")
myipCmd.Flags().BoolVarP(&rootJson, "json", "j", false, "Output the results in JSON format.")
myipCmd.Flags().BoolVarP(&rootJsonIndent, "json-indent", "", false, "Output the results in indent JSON format.")
myipCmd.Flags().BoolVarP(&rootAlfred, "alfred", "", false, "Output the results in Alfred format.")
myipCmd.Flags().StringVarP(&rootTextFormat, "text-format", "", "", UsageTextFormat)
myipCmd.Flags().StringVarP(&rootTextValuesSep, "text-values-sep", "", "", UsageTextValuesSep)
myipCmd.Flags().BoolVarP(&rootJson, "json", "j", false, UsageJson)
myipCmd.Flags().BoolVarP(&rootJsonIndent, "json-indent", "", false, UsageJsonIndent)
myipCmd.Flags().BoolVarP(&rootAlfred, "alfred", "", false, UsageAlfred)

}

var myipCmd = &cobra.Command{
Use: "myip",
Short: "Retrieve your public IP address.",
Short: "Retrieve your public IP address",
Long: `The 'myip' command uses multiple detectors to discover and return your public IP address.
It is designed to work in scenarios with multiple network interfaces and allows you to specify
the local address for outbound connections, the number of detectors to confirm the IP, and the timeout
Expand Down
27 changes: 14 additions & 13 deletions cmd/ips/cmd_pack.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,28 +25,29 @@ func init() {
rootCmd.AddCommand(packCmd)

// operate
packCmd.Flags().StringVarP(&dpFields, "fields", "f", "", "Specify the fields to be dumped from the input file. Default is all fields.")
packCmd.Flags().StringVarP(&dpRewriterFiles, "rewrite-files", "r", "", "List of files that need to be rewritten based on the given configurations.")
packCmd.Flags().StringVarP(&lang, "lang", "", "", "Set the language for the output. Example values: en, zh-CN, etc.")
packCmd.Flags().StringVarP(&dpFields, "fields", "f", "", UsageDPFields)
packCmd.Flags().StringVarP(&dpRewriterFiles, "rewrite-files", "r", "", UsageRewriteFiles)
packCmd.Flags().StringVarP(&lang, "lang", "", "", UsageLang)

// input & output
packCmd.Flags().StringVarP(&inputFile, "input-file", "i", "", "Path to the IP database file.")
packCmd.Flags().StringVarP(&inputFormat, "input-format", "", "", "Specify the format of the input file. Examples: ipdb, mmdb, etc.")
packCmd.Flags().StringVarP(&readerOption, "input-option", "", "", "Specify the option for database reader.")
packCmd.Flags().StringVarP(&outputFile, "output-file", "o", "", "Path to the packed IP database file.")
packCmd.Flags().StringVarP(&outputFormat, "output-format", "", "", "Specify the format of the output file. Examples: ipdb, mmdb, etc.")
packCmd.Flags().StringVarP(&writerOption, "output-option", "", "", "Specify the option for database writer.")
packCmd.Flags().StringVarP(&inputFile, "input-file", "i", "", UsageDPInputFile)
packCmd.Flags().StringVarP(&inputFormat, "input-format", "", "", UsageDPInputFormat)
packCmd.Flags().StringVarP(&readerOption, "input-option", "", "", UsageReaderOption)
packCmd.Flags().StringVarP(&outputFile, "output-file", "o", "", UsagePackOutputFile)
packCmd.Flags().StringVarP(&outputFormat, "output-format", "", "", UsagePackOutputFormat)
packCmd.Flags().StringVarP(&writerOption, "output-option", "", "", UsageWriterOption)

}

var packCmd = &cobra.Command{
Use: "pack -i inputFile [--input-format format] -o outputFile [--output-format format]",
Short: "Pack data from IP database file to another IP database file.",
Long: `Pack data from IP database file to another IP database file.
Short: "Repackage IP database file",
Long: `The 'ips pack' command enables users to create a new IP database file from an existing one while allowing for customization of the data fields included.
Example:
ips pack -i geoip.mmdb -o geoip.ipdb
For more detailed information and advanced configuration options, please refer to https://github.com/sjzar/ips/blob/main/docs/pack.md
`,
Example: ` # Package IP Database and Specify Fields
ips pack -i geoip.mmdb -o geoip_custom.ipdb --fields "country,city"`,
PreRun: PreRunInit,
Run: Pack,
}
Expand Down
Loading

0 comments on commit cf62af8

Please sign in to comment.