======
gingko是noah提供的基于BitTorrent的P2P文件传输工具。其主要有以下优点：
- 支持数十万台机器规模的p2p传输。
- 下载速度快
- 可进行单任务上传、下载限速以及做种机整体上传限速
- 做种过程中，任务限速、暂停、恢复等可动态改变
- 下游机器群提供多种不同源下载方式（torrent文件、infohash、http地址指定的torrent文件），尽可能满足用户自动化需求
- 支持多机做种
- 支持hdfs上的数据做种
- 优化后的上游结点选择策略，最大程度减少跨机房流量，并提高传输速度
- 支持断点续传
- 可随时查看任务状态、进度等信息
p2p tool
- gko 客户端工具（当前基于libtorrent-1.0.0-RC2）
- gko-tracker tracker服务器
- 依赖libtorrent，需要打patch（libtorrent-1.0.0-RC2.patch）
-
从libtorrent官网下载libtorrent-1.0.0-RC2
http://sourceforge.net/projects/libtorrent/files/libtorrent/libtorrent-rasterbar-1.0.0-RC2.tar.gz/download -
给libtorrent-1.0.0-RC2打patch
cd $libtorrent && patch -p1 < libtorrent-1.0.0-RC2.patch -
编译gko（需设置好相关依赖库）
cd $gko && sh build.sh -
编译gko-tracker
cd $gko-tracker && sh build.sh
-
在服务端机器部署若干台gko-tracker，启动命令
./bin/noah_control start -
在所有下载机器上启动做种客户端bbts-agent，启动命令
./NOAH/control start
##种子机做种 指定做种目录/path/to/a，做种时间1小时（3600s），种子文件保存在/path/to/a.torrent
gko3 serve -p /path/to/a -r /path/to/a.torrent -S 3600
##下载机下载 指定种子文件为之前生成的a.torrent，数据保存在目录/path/to/save
gko3 down -r /path/to/a.torrent -p /path/to/save
##gko3命令格式 gko3 operation [options] 可用的operations如下：
| operation | 说明 | operation | 说明 |
|---|---|---|---|
| mkseed | 制作种子文件 | dump | 显示种子文件内容 |
| add | 添加后台任务 | serve | 制作种子文件并做种 |
| down | 下载数据 | ||
| list | 显示任务状态 | cancel | 取消任务 |
| getopt | 查看限速等 | setopt | 设置限速等 |
| pause | 暂停任务 | resume | 恢复任务 |
gko3 mkseed -p path [r:s:C:W:l] [--besthash] [--include-files regex] [--exclude-files regex]
| -p | --path | 根目录或单个文件 | 每个种子文件中只能包含一个根目录或单文件，多个目录需首先归并到一个根目录下 |
| -r | --torrent | 种子文件 | 指定生成的种子文件名，如不指定，则以-p所指定的路径的最后一级名字作为前缀并以.torrent命令。如指定的path为/path/to/a，则默认生成的种子文件为${PWD}/a.torrent |
| -s | --size | 分块大小 | torrent中对共享文件piece的大小划分，必须是16KB的整数倍数，一般无须用户指定。 |
| -C | --cluster | 集群种子源地址 | 指定的集群地址将保存在torrent中，下载时可从该hdfs地址源下载。 |
| -W | --webseed | http种子源地址 | 指定的http地址保存在torrent中，下载时可从http为源的地址下载 |
| -l | --link | 软链是否跟随 | 指定该参数则只保存软链本身。不指定该参数即默认跟随软链所链接的实际目录或文件。 |
| --besthash | 优化hash计算 | 对于大文件来说，指定该参数能加快制作种子文件的速度。 | |
| --include-files | 指定包含的文件 | 指定包含哪些文件，支持正则表达式匹配，可指定多个。指定时需要匹配根路径下的完整path（包括根）。 | |
| --exclude-files | 指定不包含那些文件 | 指定过滤掉哪些文件，支持正则表达式匹配，可指定多个。指定时需要匹配根路径下的完整path |
gko3 dump -r torrent
| -r | --torrent | 种子文件 | 指定要查看的种子文件路径。 |
gko3 add (-r torrent | -i infohash) (-p path | -n fullpath) -S seedtime [u:c:] [--seed] [--tracker tracker]
| -r | --torrent | 种子文件 | 根据种子文件进行下载 |
| -i | --infohash | infohash | 根据infohash进行做种/下载，infohash即可通过mkseed/dump/serve中输出来获取，可唯一标志一份种子文件内容。 |
| -p | --path | 数据保存目录 | 对于做种任务：做种的源数据必须保存在此路径下；对于后台下载的任务：下载的数据会保存在该目录内 |
| -n | --fullpath | 数据根目录/文件名 | 该参数可更改（重命名）种子文件中数据的根目录/文件，指定该参数会忽略-p参数。 |
| -S | --seedtime | 做种时间 | 即成为种子后提供上传服务的时间，超时任务退出。若不提供该值，则会默认计算一个时间。-1为一直做种，直到用户cancel该任务 |
| -u | --uplimit | 上传限速 | 该任务共享给他人的最大带宽，单位MB/s |
| -c | --connlimit | 最大连接数 | 该任务与其他peer建立连接的最大数目 |
| --seed | 指定为做种任务 | 默认不指定为做种任务，指定该参数表示该数据已经存在，只进行后台做种即可。 | |
| --tracker | 指定特定tracker | 请求特定的tracker，格式host:port，可指定多个，多个tracker按顺序连接，第一个不可用才会重试第二个 |
gko3 serve -p path -S seedtime [u:c:r:s:l] [--besthash] [--include-files] [--exclude-files]
| -p | --path | 数据根目录或单个文件 | 该参数与mkseed中指定的-p参数相同，与add中的-n参数相同，有别于add中-p为数据根目录的上级目录 |
| -r | --torrent | 种子文件 | 指定生成的种子文件名，如不指定，则以-p所指定的路径的最后一级名字作为前缀并以.torrent命令。如指定的path为/path/to/a，则默认生成的种子文件为${PWD}/a.torrent |
| -S | --seedtime | 做种时间 | 做种时间，单位s，做种完成后任务退出。做种任务必须提供该值，否则会直接退出。-1为一直做种，直到用户cancel该任务 |
| -u | --uplimit | 上传限速 | 该任务共享给他人的最大带宽，单位MB/s |
| -c | --connlimit | 最大连接数 | 该任务与其他peer建立连接的最大数目 |
| -s | --size | 分块大小 | torrent中对共享文件piece的大小划分，必须是16KB的整数倍数，一般无须用户指定。 |
| -l | --link | 软链是否跟随 | 指定该参数则只保存软链本身。不指定该参数即默认跟随软链所链接的实际目录或文件。 |
| --besthash | 优化hash计算 | 对于大文件来说，指定该参数能加快制作种子文件的速度。 | |
| --include-files | 指定包含的文件 | 指定包含哪些文件，支持正则表达式匹配，可指定多个。指定时需要匹配根路径下的完整path（包括根）。 | |
| --exclude-files | 指定不包含那些文件 | 指定过滤掉哪些文件，支持正则表达式匹配，可指定多个。指定时需要匹配根路径下的完整path | |
| --tracker | 指定特定tracker | 请求特定的tracker，格式host:port，可指定多个，多个tracker按顺序连接，第一个不可用才会重试第二个 |
##down 下载使用down命令，命令格式如下：
gko3 down (-r torrent | -i infohash) (-p path | -n fullpath) [S:O:d:u:c:C:W:P:] [--include-files] [--exclude-files]
下载时需要至少提供一种方式来指定种子源：
- 种子文件
- infohash
- http-url指定的种子文件地址
| -r | --torrent | 种子文件 | 根据种子文件进行下载 |
| -i | --infohash | infohash | 根据infohash进行下载，infohash即可通过mkseed/dump/serve中输出来获取，可唯一标志一份种子文件内容。 |
| -p | --path | 数据保存目录 | 下载的数据会保存在该目录内 |
| -n | --fullpath | 数据根目录/文件名 | 该参数可更改（重命名）种子文件中数据的根目录/文件，指定该参数会忽略-p参数。 |
| -S | --seedtime | 做种时间 | 即下载完成后，继续做种的时间。若不提供该值，则会默认计算一个时间。-1会被忽略。 |
| -O | --timeout | 超时时间 | 如果超过该值还未完成下载，则下载进程退出。单位s |
| -d | --downlimit | 下载限速 | 下载限速阈值，单位MB/s |
| -u | --uplimit | 上传限速 | 上传限速阈值，单位MB/s |
| -c | --connlimit | 最大连接数 | 该任务与其他peer建立连接的最大数目 |
| -C | --cluster | 集群种子源地址 | 指定该参数，下载将以hdfs作为一个确定的数据源进行下载 |
| -W | --webseed | http种子源地址 | 指定该参数，下载将以http作为一个数据源进行下载，目前只支持种子为单文件，不支持目录。 |
| -P | --port | bind端口范围 | 下载进程绑定的端口，供p2p上传数据使用。逗号分隔，e.g. -P 6881,6889 |
| --offline | 绑定离线端口 | 指定该参数，默认绑定sys指定的离线端口进行下载 | |
| --besthash | 优化hash计算 | 对于大文件来说，指定该参数能加快制作种子文件的速度。 | |
| --include-files | 指定下载的文件 | 指定下载哪些文件，支持正则表达式匹配，可指定多个。指定时需要匹配根路径下的完整path（包括根）。 | |
| --exclude-files | 指定下载过滤哪些文件 | 指定过滤掉哪些文件不下载，支持正则表达式匹配，可指定多个。指定时需要匹配根路径下的完整path | |
| --hang-timeout | 检测下载hang住超时值 | 超过此时间没有下载1B数据，则认为下载没有数据源hang住，自动退出。默认15分钟 | |
| --progress | 输出下载进度 | 在标准输出打印出进度，每2s刷新一次。 | |
| --continue | 快速恢复断点续传 | 指定该参数，下载被中断，重试时可跳过check文件数据阶段，直接从上次进度开始下载 | |
| --tmp-files | 先下载到临时文件，在mv到正式目录 | 下载时不直接下载到目标目录，而是先下载到目标目录下的临时目录中，下载成功在mv到正式目录下 | |
| --debug | 调试模式 | 追问题是可打开调试模式，输出更多debug日志 | |
| --unix-socket | 指定与该下载进程通信的unix socket path | 通过指定该参数，用户可通过该unix socket path动态调整该下载进程的限速等 | |
| --save-torrent | 保存下载到的种子文件 | 通过infohash下载时，使用该参数可将下载到的种子文件保存在本地指定文件中 | |
| --ip-write | ip白名单 | 只有在该白名单中的ip才会建立连接。格式: --ip-write=startip[-endip][,...] | |
| --ip-black | ip黑名单 | 出现在该黑名单中的ip不会与之建立连接。格式: --ip-black=startip[-endip][,...] | |
| --mask | 掩码 | 类似子网掩码的机制，若下载机ip为10.26.38.49，指定--mask=255.255.0.0，则与指定--ip-white=10.26.0.0-10.26.255.255相同 | |
| --numwant | 一次获取的peers数目 | 从tracker中一次获取的peers数目，默认25个 | |
| --ainterval | 与tracker通信的最大周期 | announce请求的最大周期，单位s，默认100s | |
| --sndbuf | 发送缓冲区大小 | 与其他peers通信的发送缓冲区大小 | |
| --rcvbuf | 接收缓冲区大小 | 与其他peers通信的接收缓冲区大小 | |
| --hdfs-thread | hdfs下载线程数 | 从hdfs上下载时，起的线程数目 | |
| --tracker | 指定特定tracker | 请求特定的tracker，格式host:port，可指定多个，多个tracker按顺序连接，第一个不可用才会重试第二个 | |
| --tracker-failed-quit | 连不上tracker退出 | 若连不上所有tracker，则报错退出 | |
| --use-dio-read | 磁盘读使用DIO | 所有读磁盘操作为DIO方式 | |
| --use-dio-write | 磁盘写使用DIO | 所有写磁盘操作为DIO方式 | |
| --ignore-hdfs-error | 忽略hdfs错误 | 从hdfs下载数据时，若出现读失败等，暂不退出，尝试从其他peer获取数据，并每15s检测一下hdfs上数据是否可用 | |
| --mem-limit | 内存阈值 | 超过指定的阈值则下载进程退出，检测周期为15s，单位MB | |
| --pre-allocate | 磁盘空间预分配 | 下载前对文件的磁盘空间预分配，使用该模式可减少文件的碎片数，但相应的会延长下载时间 | |
| --d-allocate | 动态磁盘空间预分配 | 该参数和--pre-allocate类似，不过是边下载边分配空间，相比--pre-allocate，可以减少下载时间，但同时也会增加文件的碎片数。该参数需要指定每次预分配的块数，实测30-50能在时间和碎片数上达到较好的平衡 |
##list list命令可查看目前所有后台任务
gko3 list [-t taskid ...] [-a attributes] [--noheader]
| -t | --task | 后台任务id | 不指定-t则显示所有任务信息，否则显示特定的任务信息，批处理可指定多个-t |
| -a | --attr | 显示属性 | 需要显示的任务属性 |
| --noheader | 不显示标题 | 输出不显示标题行 |
| taskid | 任务id | status | 任务状态 |
| infohash | 种子文件的infohash | progress | 下载进度百分比 |
| user | 添加任务的属主 | group | 添加任务的属组 |
| cmd | 添加任务的完整命令行 | error | 若有错误，返回错误信息 |
| upload | 上传数据总量，单位bytes | uprate | 当前上传速度，单位B/s |
| peers | 本任务已知的peers数目 | seeds | 本任务已知的种子任务数 |
| savepath | 数据保存根路径 |
这三个命令，除root用户外，其他用户只能操作本用户创建的任务。
gko3 cancel [-t taskid ...] [--all]
gko3 pause [-t taskid ...] [--all]
gko3 resume [-t taskid ...] [--all]
| -t | --task | 后台任务id | -t和--all必须指定其一；否则显示特定的任务信息，批处理可指定多个-t |
| --all | 所有任务 | 指定所有本用户所添加的任务 |
gko3 getopt [-t taskid | --unix-socket path]
不指定-t或--unix-socket则输出全局限速信息；指定-t，输出特定做种任务的限速信息。指定--unix-socket则输出该下载任务的限速信息。该参数需要与down中该参数搭配使用。 ##setopt 修改bbts-agent全局限速，或某个后台做种任务的限速，或设定unix sockt path的一个下载任务的限速。目前只有root用户可以修改全局限速，其他用户只能修改本用户添加任务的配置信息。
gko3 setopt [-t taskid | --unix-socket path] [-d downrate] [-u uprate] [-c connlimit]
##hdfs下载 从hdfs上进行p2p下载数据时，需要分两步进行： ###生成种子文件*.torrent 生成种子文件有两种方式，如下：
- （1）源数据本身在某台单机上，那么在该机器上执行gko3 mkseed命令生成一份种子文件
- （2）源数据在hdfs集群上，那么可使用我们的分布式做种工具hadoopseed进行做种。具体使用方式请参考
###下载数据 下载命令行参考gko3 down。如果是单机生成的torrent文件，在没有指定数据在hdfs上的地址的情况下，需要通过指定-C参数来确定
gko3 down -r *.torrent -p ./ -C hdfs://user:passwd@namenode:port/path
当然，mkseed的时候也可以统一指定-C参数，这样数据在集群上的地址会写入到torrent文件中去，下载时无须重复指定（如重复指定以下载时指定的hdfs地址为主）
gko3 mkseed -p path -r *.torrent -C hdfs://user:passwd@namenode:port/path
##hadoopseed使用说明
###简介
hadoopseed工具随gko3一起上线，同样会在/usr/bin下打个软链。该工具用来对hdfs集群上某个数据进行计算，生成种子文件*.torrent供gingko 3.0进行基于hdfs的p2p下载。
###前提条件
使用hadoopseed需要python/java/hadoop支持，目前noah已未全百度绝大部分机器部署了这些基础工具，部署路径在/home/opt，没有部署的可能是磁盘inode数不足等原因，使用hadoopseed前请确定/home/opt下的工具是可用的。如不可用请联系noah_help协助部署。
###使用方式 hadoopseed -u user,passwd -H NameNode:port -T JobTracker:port -d 集群目录 (-f 本地torrent文件 | -F 远程torrent文件) [-s 分块大小]
| -u | --ugi | 用户名密码 | 用户必须有执行MR任务的权限，用户名密码以逗号分隔 |
| -H | --hadoop_host | namenode:port | hdfs namenode及其端口，以冒号分隔 |
| -T | --hadoop_tracker | jobtracker:port | hadoop jobtracker及其端口，以逗号分隔 |
| -f | --torrent_file | 本地种子文件路径 | 生成的种子文件保存在本地的路径 |
| -F | --hdfs_torrent_file | hdfs上种子文件路径 | 生成的种子文件保存在hdfs上的路径；-f -F指定其一即可 |
| -s | --piece_size | 分块大小 | torrent中对共享文件piece的大小划分，默认8MB，一般无须用户指定。 |
gko3 down –r .torrent –p path