{
    "info": {
        "author": "Ivan Shapovalov",
        "author_email": "intelfx@intelfx.name",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 3 - Alpha",
            "License :: OSI Approved :: GNU Affero General Public License v3",
            "Programming Language :: Python :: 3.7",
            "Programming Language :: Python :: 3 :: Only"
        ],
        "description": "# upenwrt\n\n[![PyPI version](https://badge.fury.io/py/upenwrt.svg)](https://badge.fury.io/py/upenwrt)\n\n`upenwrt` is a tool, in form of a (simple) HTTP server, that generates custom\n[OpenWRT][1] sysupgrade images with all your user-installed packages baked in,\non the fly.\n\nIt is designed to aid end-user upgrade process (saving you the hassle of\nreinstalling all your packages by hand), especially if the target device relies\non non-default packages for Internet connectivity.\n\n[1]: https://openwrt.org\n\n# usage\n\nAssuming that the daemon is reachable at <http://upenwrt:8000>:\n\n```\ncurl http://upenwrt:8000/get | sh > /tmp/sysupgrade.img\nsysupgrade -v /tmp/sysupgrade.img\n```\n\nFiles read by the script:\n\n* `/etc/openwrt_release`\n* `/tmp/sysinfo/board_name`\n* `/usr/lib/opkg/status`\n\nCommand-line arguments and environment variables used by the script:\n\n| Command-line argument                 | Environment variable        | Description                                                                     | Default                                                 |\n|---------------------------------------|-----------------------------|---------------------------------------------------------------------------------|---------------------------------------------------------|\n| `--debug`                             | `$DEBUG`                    | enable (more) verbose logging in the script itself                              | not set                                                 |\n| `--dry-run`                           | `$DRY_RUN`                  | do not call the server, only generate the curl(1) command line                  | not set                                                 |\n| `--hw-target`                         | `$TARGET_NAME`              | OpenWRT target name, e. g. `ramips/mt7621`                                      | overrides `$DISTRIB_TARGET` of `/etc/openwrt_release`   |\n| `--hw-target`                         | `$TARGET_NAME`              | OpenWRT target name, e. g. `ramips/mt7621`                                      | overrides `$DISTRIB_TARGET` of `/etc/openwrt_release`   |\n| `--hw-board`                          | `$BOARD_NAME`               | OpenWRT board name or profile name, e. g. `xiaomi,mir3g` or `mir3g`             | overrides `/tmp/sysinfo/board_name`                     |\n| `--current-release`                   | `$RELEASE`                  | current (installed) OpenWRT release, e. g. `SNAPSHOT`                           | overrides `$DISTRIB_RELEASE` of `/etc/openwrt_release`  |\n| `--current-revision`                  | `$REVISION`                 | current (installed) OpenWRT revision, e. g. `r10574-273b803623`                 | overrides `$DISTRIB_REVISION` of `/etc/openwrt_release` |\n| `--packages`                          | `$PACKAGES`                 | list of packages to install into the image, space-separated                     | overrides `/usr/lib/opkg/status`                        |\n| `--packages-add`, `--packages-remove` | `$PKGS_ADD`, `$PKGS_REMOVE` | lists of packages to add/ignore when installing into the image, space-separated | none (supplements `/usr/lib/opkg/status`)               |\n\n# description\n\n`upenwrt` is implemented as a (simple) HTTP server daemon that serves a help\npage (`/`), a script (`/get`) and an API endpoint (`/api/get`).\n\nThe script must be executed on the target device (presumably in the infamous\n`curl | sh` pattern) and will collect user-installed package lists and other\nnecessary metadata. The API endpoint is supposed to be called by the script\nand will return the resulting image in the response body (which will be written\non stdout).\n\n# daemon usage\n\nThe daemon keeps all of its data in its \"root directory\", henceforth `$rootdir`.\n\nInside its `$rootdir`, the daemon needs:\n* a copy of its static file tree under `$rootdir/static`\n  (included in upenwrt source tree as `root/static`)\n* a copy of [OpenWRT git repository][2] under `$rootdir/repo/openwrt.git`\n  (bring your own and fetch regularly, upenwrt will not update it)\n* an empty cache directory `$rootdir/cache`\n* an empty work directory `$rootdir/work`\n\nIt is advised to put the work directory (`$rootdir/work`) on tmpfs and the cache\ndirectory (`$rootdir/cache`) on a persistent read-write medium with sufficient\nstorage capacity for a few imagebuilders.\n\nIn other words:\n\n```\nmkdir -p /var/lib/upenwrt\ncp -r root/static -T /var/lib/upenwrt/static\nmkdir -p /var/lib/upenwrt/repo; git clone --bare https://git.openwrt.org/openwrt/openwrt.git /var/lib/upenwrt/repo/openwrt.git\nmkdir -p /var/lib/upenwrt/cache\nmkdir -p /var/lib/upenwrt/work; mount tmpfs -t tmpfs /var/lib/upenwrt/work\n\npython -m upenwrt --rootdir /var/lib/upenwrt --baseurl http://upenwrt:8000 --listen '0.0.0.0' --port 8000\n```\n\n[2]: https://git.openwrt.org/openwrt/openwrt.git\n\n# trivia\n\nThe main problem is to separate truly user-installed packages from default\npackages (which are marked \"user\" in the opkg database as well), because while\nit is possible to pass all \"user\" packages to `make image`, the default package\nset is much more prone to change between revisions than user packages.\n\nThe obvious idea would be to compare opkg databases between the squashfs and the\noverlay. However, this will not work if the user already runs an image with some\nof their packages baked in (or, by extension, if the tool is used twice or more\nin a row). The only viable idea known to the author is to get a vanilla openwrt\nimage of a matching revision and use its package list as the base.\n\nHowever, it is infeasible to download and keep vanilla images corresponding to\nall possible source revisions (as they are, naturally, rotated daily). Instead,\nthe openwrt source tree is downloaded and cached. Upon each request, the source\ntree is checked out at the revision matching the pre-existing firmware and\ntargetinfo files are generated by calling the buildsystem. \"Vanilla\" package\nlists are then extracted from targetinfo files and subtracted from submitted\npackage lists.\n\n# license\n\nThis project is distributed under the terms of the [GNU Affero General Public\nLicense (AGPL), version 3][4].\n\n    This program is free software: you can redistribute it and/or modify\n    it under the terms of the GNU Affero General Public License, version 3\n    as published by the Free Software Foundation.\n\n    This program is distributed in the hope that it will be useful,\n    but WITHOUT ANY WARRANTY; without even the implied warranty of\n    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n    GNU Affero General Public License for more details.\n\n    You should have received a copy of the GNU Affero General Public License\n    along with this program.  If not, see <http://www.gnu.org/licenses/>.\n\n[4]: https://www.gnu.org/licenses/agpl-3.0.en.html",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/intelfx/upenwrt",
        "keywords": "",
        "license": "",
        "maintainer": "",
        "maintainer_email": "",
        "name": "upenwrt",
        "package_url": "https://pypi.org/project/upenwrt/",
        "platform": "",
        "project_url": "https://pypi.org/project/upenwrt/",
        "project_urls": {
            "Homepage": "https://github.com/intelfx/upenwrt"
        },
        "release_url": "https://pypi.org/project/upenwrt/0.1.1/",
        "requires_dist": null,
        "requires_python": ">=3.7",
        "summary": "A tool that generates custom OpenWRT sysupgrade images",
        "version": "0.1.1"
    },
    "last_serial": 5974657,
    "releases": {
        "0.1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "b0aecacff48d4bf56c0e6e5bfd69f89d",
                    "sha256": "d10679f774d138966274dbddbfbc5db4174df0b7d2b7ff8fa9bdd2032ad619dc"
                },
                "downloads": -1,
                "filename": "upenwrt-0.1.0.tar.gz",
                "has_sig": false,
                "md5_digest": "b0aecacff48d4bf56c0e6e5bfd69f89d",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.7",
                "size": 15861,
                "upload_time": "2019-10-15T01:29:00",
                "url": "https://files.pythonhosted.org/packages/73/67/32eefcc6396673b1f44fef72ec6222f7babdd32b8dc85d62c1b8b0bde6bf/upenwrt-0.1.0.tar.gz"
            }
        ],
        "0.1.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "82b5cb31c3110f64d26d569b5bdfb445",
                    "sha256": "2441c134c27d5fa8874c69b01883eb44b08bb4184aa508c74dc28b0b6c1fea4d"
                },
                "downloads": -1,
                "filename": "upenwrt-0.1.1.tar.gz",
                "has_sig": false,
                "md5_digest": "82b5cb31c3110f64d26d569b5bdfb445",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.7",
                "size": 15954,
                "upload_time": "2019-10-15T03:55:20",
                "url": "https://files.pythonhosted.org/packages/ca/96/037d2a6f9011a89693af1f37a0e5f7e831315e370dbf101e46459fae0e3b/upenwrt-0.1.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "82b5cb31c3110f64d26d569b5bdfb445",
                "sha256": "2441c134c27d5fa8874c69b01883eb44b08bb4184aa508c74dc28b0b6c1fea4d"
            },
            "downloads": -1,
            "filename": "upenwrt-0.1.1.tar.gz",
            "has_sig": false,
            "md5_digest": "82b5cb31c3110f64d26d569b5bdfb445",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 15954,
            "upload_time": "2019-10-15T03:55:20",
            "url": "https://files.pythonhosted.org/packages/ca/96/037d2a6f9011a89693af1f37a0e5f7e831315e370dbf101e46459fae0e3b/upenwrt-0.1.1.tar.gz"
        }
    ]
}