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 提交一个定时任务, 在今天半夜时刻踢掉所有在线用户.
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). 这导致在较新的系统上官方客户端完全失效.

附注: 在更新的系统上, bind() 到 AF_UNSPEC 类型的地址被允许用于地址为 INADDR_ANY, 见 Linux commit 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.