English
资源说明：为 Linux/BSD 编写的北师大认证网关开源客户端 An open-source, cross-platform, enhanced client for Beijing Normal University's Internet authentication/payment gateway.
# pysrun pysrun 是用 Python 编写的北师大上网认证网关客户端. ## 使用说明 ### 快速入门三部曲 1. 下载文件后, 用您惯用的文本编辑器, 打开 `pysrun.cfg.default` 这个文件. 2. 修改这个文件, 在 `interface=` 后面填入您网络连接的界面名称 (`ifconfig` 命令可以帮您查看). 在 `username` 和 `password` 后面分别填入您从学校处获得的用户名和密码. 保存这个文件到您主目录下这个路径 `~/.pysrun.cfg`. 3. 运行命令 `./pysrun login`. 这就可以登录学校网络了. 完成入门三部曲后, 您可能希望将 `pysrun` 这个可执行文件拷入 `PATH` 环境变量所包括的目录路径下 (可能需要相关权限). 如果您觉得必要, 也可以设置配置文件 `~/.pysrun.cfg` 的可读权限, 保护您信息的安全. 更多进阶说明, 请继续阅读本文档. ### 安装 本脚本无需安装其它程序库, 只需要下载即可执行. 需要用到的文件有两个: 1. `pysrun`: 可执行 Python 脚本, 2. 配置文件, 默认路径为 `~/.pysrun.cfg`. 软件包提供了样例配置文件 `pysrun.cfg.default`. 第一次使用前, 建议将其拷贝到 `~/.pysrun.cfg`, 同时填入包括用户名密码在内的相关信息. 您可以将可执行文件 `pysrun` 放在任何路径下, 建议放在 `PATH` 环境变量所包含的目录下. 严格说来, 配置文件不是必须的. 但是, 因为选项一般很少改动, 使用配置文件会比较方便. ### 配置文件 配置文件分为如下部分, 每个部分中有若干个选项. 1. `[Server]` 填写北师大认证服务器信息. 除非有很特殊的情况, 请不要修改这组选项. * `address`: 服务器 IP 地址或主机名. 默认值: 172.16.202.201. * `port`: 服务器监听端口. 客户端通过向这个端口上监听的服务器发送信息来工作. 默认值: 3333. 2. `[Client]` 用于配置客户端所运行需要的主机信息. * `interface`: 在哪个网络界面上认证. 此界面的MAC地址将成为认证信息的一部分. 对于登入和登出操作, 如果此界面可用, 则用于同认证服务器的通信的本地套接字都将 `bind()` 到该界面的 IP 地址. 默认值: eth0 (小窍门: 请查看 `ifconfig` 之类命令的输出决定界面的名称). 3. `[Account]` 填写用户帐号信息. * `username`: 帐号 (通常为学工号), 无默认值. * `password`: 密码, 无默认值. 4. `[Session]` 用于配置会话状态的保存. * `uidfile`: 保存所谓 "uid" 信息的文件路径. 每次登入, 服务器会返回一个 uid. 登出时需要使用这个 uid 退出. `uidfile` 路径所指示的文件用来存放每次登入所返回的uid. 在登出前, 不要修改这个文件的内容或者移动乃至删除这个文件. 默认值: `~/.pysrun_uid`. 配置文件的格式要求如下: 1. 文件由行组成. 满足合格要求的行, 必须是 `key = value` 的形式. 主键 (key), 等号和键值 (value) 都可以被任意多的空白字符 (如空格和制表符) 所包围, 空白字符可以出现在主键或键值中, 但不能是开头或结尾的字符. 如果有多个等号, 第一个等号为主键和键值的分隔符, 其余为键值的一部分. 2. 满足合格要求的主键-键值对, 其主键或键值都不能为空. 3. 注释文字以井号 (`#`) 开始. 4. 任何不满足以上要求的行, 都被忽略. 可以认为它们都是注释. 5. 如果一个主键在文件中重复出现, 最后一次出现的合格键值起作用. 在配置文件中, 上述被中括号括起来的部分 (如 `[Server]` ) 起到每一节标题的作用. 在 0.4 版本以前, 它们必须如此. 自从 0.4 版本开始, 它们可以被彻底删去, 不发挥任何作用, 相当于文件格式第 4 条所描述的注释. 我们建议您不再使用中括号定义的标题, 最好是替换成用 `#` 符号开始的注释, 以增加配置文件的可读性. ### 命令行选项 上述配置文件中的选项, 都有命令行的对应体. 因此, 本程序在没有配置文件 (或者配置文件不包含任何可辨认的内容) 的情况下也可以使用. 命令行选项如下所述: * `-u USERNAME`: 用于指出用户名, 对应于配置文件的 `username` 选项. * `-p PASSWORD`: 用于指出密码, 对应于配置文件的 `password` 选项. * `-a ADDRESS`: 认证服务器地址或主机名, 对应于配置文件的 `address` 选项 * `-P PORT`: 认证服务器通信端口, 对应于配置文件的 `port` 选项. * `-i INTERFACE`: 用于获取 MAC 地址的网络界面, 对应于 `interface` 选项. * `-s FILE`: "uid"信息存储文件的路径, 对应于 `uidfile` 选项. * `-l FILE`: 日志文件路径. 如果文件不存在, 将被尝试创建. 如果不提供此 `-l` 选项, 将不记录日志. 如果 `-d` 选项 (见下文) 启用, 将记录大量有助于调试的信息, 否则只记录异常情况信息. 对应于配置文件的 `logpath` 选项. *请注意!* 以上命令行选项都优先于配置文件发挥作用. 也就是说, 一旦命令行给出了某选项, 那么无论在配置文件中如何设置, 都以命令行选项为准. 更多命令行特有的选项如下: * `-c FILE`: 指定配置文件路径, 用于提供不同于默认路径 (`~/.pysrun.cfg`) 的配置文件. 小窍门: 用 `-c /dev/null` 可以彻底告别配置文件. * `-I`: 交互式输入密码. 输入的内容将不会回显. 用于不打算保存密码的情况. 如果使用这一选项, 则交互式输入的内容优先于其它方式给出的密码. * `-d`: 打开调试信息显示. 如果启用日志 (见上文), 将使日志中出现调试信息. * `-h`: 显示使用帮助信息并退出, 不进行任何操作. ### 登入, 登出和强制离线操作 1. 登入: 使用 `pysrun login` 命令. 登入成功后主程序将安静地退出. 需要提供 `username`, `password` 和 `interface` 选项. 2. 登出: 使用 `pysrun logout` 命令. 需要知道网络界面和 uid, 因此须提供 `uidfile` 选项. 3. 强制离线: 又称踢人, 即让所有占用这个帐号的IP地址离线, 使用 `pysrun kick` 命令. 需要提供 `username` 和 `password` 选项. *注意:* 需要让 `pysrun` 所在目录在您的 `PATH` 环境变量中, 否则应使用类似 `./pysrun` 的绝对路径启动程序. ### 主程序返回值 * 0: 程序正常退出. 意外仍然可能发生, 例如登录成功但是服务器返回的 uid 无法写入文件里. 这种情况下会有警告信息提示, uid 也会回显在警告信息里. * 1: 操作失败, 并且服务器返回了一条状态解释失败的原因. 通常是因为人数达到上限, 欠费, 或者在无人在线时强制所有人离线等原因造成. * 2: 程序因选项配置错误而退出. * 4: 操作系统返回错误, 例如网络不可达, 读文件失败, 或者指定的网络界面无 MAC 地址. * 8: 服务器返回了不符合意料格式的信息, 实际操作的状态未知, 不可知, 或未定义. ### 背景进程 登录成功后, 两个守护进程将留在背景中执行. 其中之一等待将会到来的 `login`, `logout` 或 `kick` 命令, 另一个每隔1分钟左右向认证服务器发出一个 heartbeat 数据包, 以保持和服务器的通信, 不至于一段时间无活动后断网. 在旧 Linux 客户端登录模式下没有这个保持连接功能. 当执行任何新的登入, 登出和踢人操作后, 背景进程都将得到自动关闭的命令, 将立刻自行退出. 如果被别的用户以任何方式踢掉, 背景进程也将在1分钟内退出. (被踢后保持背景通信是没有意义的, 即使这样做也不能继续使用网络.) 两守护进程相互监视, 其中之一退出后另一个将立即退出. 背景进程正常停止工作将以 0 退出, 否则以非 0 值退出. 正常情况下, 背景进程工作过程中需要在临时文件目录 `/tmp` 下打开一个 UNIX domain socket 文件 `/tmp/pysrun.sock`. 工作过程中, 如果用移除或其它任何办法导致此文件不可用, 将产生无法确定的结果. ### 用法示例 1. `pysrun -c /dev/null -i wlan0 -u USERNAME -p PASSWORD login` 使用 wlan0 界面的 MAC 地址, 不读取任何配置文件 (即只用默认值), 登入. 2. `echo 'pysrun kick' | at midnight` 通过 [`at`][at-man] 提交一个定时任务, 在今天半夜时刻踢掉所有在线用户. 3. 有时候, 在登出或者踢人后立刻重新登录, 服务器会认为你已经登录从而返回错误. 这时候只需要等上片刻即可, 或者, 假如你知道这的确是出错的唯一原因, 可以在bash下使用类似 `until pysrun login; do sleep 1; done` 的命令来自动地反复重试. 如果不想看到每次重试产生的错误信息, 可以将其转接到 `/dev/null`: `until pysrun login 2> /dev/null; do sleep 1; done` 更好的方式是将返回值检查包括进来: ``pysrun kick && while [[ `pysrun login 2> /dev/null; echo $?` -eq 1 ]]; do sleep 1; done`` ## 适用系统 目前在 Linux 系统上经过基本测试. 在各种 BSD 系统上 (包括Free/Net/Open/DragonFlyBSD) 也可以使用, 但未经过测试. 本程序不依赖于系统是 32 或 64 位. 正确执行当前版本需要 Python 2.7. ## 背景 北师大提供的"官方" Linux 命令行客户端是一个动态编译的 32 位程序. 它具有如下不足: * 不适用于 64 位系统, 需要在 64 位系统上再安装 32 位 C 标准库. * 是"黑箱"程序, 无源码, 不知其工作原理, 必须诉诸逆向工程. * 没有提供合理的配置方法, 亦不返回有用的返回值, 因此几乎无法自动化. * 自 Linux 2.6.35 后, 出现了官方客户端无法使用的情况. 其原因是官方客户端在进行 `bind()` 调用时采取了不规范的用法, 被较新的内核认为是错误的调用而无法执行 (参见 https://lkml.org/lkml/2011/7/9/37, 或 [Linux commit d0733d2e][d0733d2e]). 这导致在较新的系统上官方客户端完全失效. > 附注: 在更新的系统上, `bind()` 到 `AF_UNSPEC` 类型的地址被允许用于地址为 `INADDR_ANY`, 见 [Linux commit 29c486df][29c486df], 而这也正是官方客户端所做的. 所以对于此 commit 以后的内核版本, 上一点不能用于作为否定官方客户端的较强论据. * 它使用的登录认证模式经常被北师大自己在服务器端禁用. 北师大提供的另一个客户端是个 GTK 图形界面程序. 除了上述缺点同样存在以外, 它显然不能在纯命令行环境下运行. 无论是图形界面还是文字界面下的"官方"客户端, 都存在很多错误或问题, 这些问题没有任何说明, 是在使用中发现的. 我们在 GitHub 的 Wiki 页面上列举了其中的一些问题 (https://github.com/congma/pysrun/wiki/BugsInOriginalClients). 此外, 北师大也没有给出对各种 BSD 系统的支持. 尽管一些 BSD 系统建有 Linux 兼容层或模拟层, 但通过兼容层运行本来就编写甚为 sloppy 的 Linux 程序可能导致难以预料的结果. 因此, 我们需要一个新的客户端可以改变以上所列的不足. 新客户端原生地支持 Linux 和各种 BSD, 支持 32 位和 64 位系统, 有开放的源码, 而且避免了原客户端中的不规范编程. 特别的一点是, 它具有功能完整的命令行和配置文件界面, 并且有确定的返回值, 可以很直接地实现自动化, 如实现 SysV 起始脚本 (init script). 因此我们建议应该用此客户端取代官方客户端. ## 报告错误 请通过 GitHub 的事项追踪功能汇报错误: https://github.com/congma/pysrun/issues ## 授权 BSD 许可证, 见文件 COPYRIGHT. ## 版本信息 2013-03-18 version 1.0.10. [d0733d2e]: https://github.com/torvalds/linux/commit/d0733d2e29b652b2e7b1438ececa732e4eed98eb "Linux commit d0733d2e29b652b2e7b1438ececa732e4eed98eb" [29c486df]: https://github.com/torvalds/linux/commit/29c486df6a208432b370bd4be99ae1369ede28d8 "Linux commit 29c486df6a208432b370bd4be99ae1369ede28d8" [at-man]: http://linux.die.net/man/1/at "Linux manual page for at(1)"
本源码包内暂不包含可直接显示的源代码文件，请下载源码包。
