Skip to content
/ pysrun Public

为 Linux/BSD 编写的北师大认证网关开源客户端 An open-source, cross-platform, enhanced client for Beijing Normal University's Internet authentication/payment gateway.

License

Notifications You must be signed in to change notification settings

congma/pysrun

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

pysrun

pysrun 是用 Python 编写的北师大上网认证网关客户端.

使用说明

快速入门三部曲

  1. 下载文件后, 用您惯用的文本编辑器, 打开 pysrun.cfg.default 这个文件.
  2. 修改这个文件, 在 interface= 后面填入您网络连接的界面名称 (ifconfig 命令可以帮您查看). 在 usernamepassword 后面分别填入您从学校处获得的用户名和密码. 保存这个文件到您主目录下这个路径 ~/.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.
  1. [Client] 用于配置客户端所运行需要的主机信息.
  • interface: 在哪个网络界面上认证. 此界面的MAC地址将成为认证信息的一部分. 对于登入和登出操作, 如果此界面可用, 则用于同认证服务器的通信的本地套接字都将 bind() 到该界面的 IP 地址. 默认值: eth0 (小窍门: 请查看 ifconfig 之类命令的输出决定界面的名称).
  1. [Account] 填写用户帐号信息.
  • username: 帐号 (通常为学工号), 无默认值.
  • password: 密码, 无默认值.
  1. [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, passwordinterface 选项.
  2. 登出: 使用 pysrun logout 命令. 需要知道网络界面和 uid, 因此须提供 uidfile 选项.
  3. 强制离线: 又称踢人, 即让所有占用这个帐号的IP地址离线, 使用 pysrun kick 命令. 需要提供 usernamepassword 选项.

注意: 需要让 pysrun 所在目录在您的 PATH 环境变量中, 否则应使用类似 ./pysrun 的绝对路径启动程序.

主程序返回值

  • 0: 程序正常退出. 意外仍然可能发生, 例如登录成功但是服务器返回的 uid 无法写入文件里. 这种情况下会有警告信息提示, uid 也会回显在警告信息里.
  • 1: 操作失败, 并且服务器返回了一条状态解释失败的原因. 通常是因为人数达到上限, 欠费, 或者在无人在线时强制所有人离线等原因造成.
  • 2: 程序因选项配置错误而退出.
  • 4: 操作系统返回错误, 例如网络不可达, 读文件失败, 或者指定的网络界面无 MAC 地址.
  • 8: 服务器返回了不符合意料格式的信息, 实际操作的状态未知, 不可知, 或未定义.

背景进程

登录成功后, 两个守护进程将留在背景中执行. 其中之一等待将会到来的 login, logoutkick 命令, 另一个每隔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.

About

为 Linux/BSD 编写的北师大认证网关开源客户端 An open-source, cross-platform, enhanced client for Beijing Normal University's Internet authentication/payment gateway.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages