i2p.newsxml/README

Package Requirements:
	python
	python-dev
	python-virtualenv
	libxml2-dev
	libxslt1-dev
	tx client to push/pull translations

To set up:

$ ./setup_venv.sh
$ . env/bin/activate
$ pip install .

Copy etc/su3.vars to etc/su3.vars.custom
Change settings for your signing key name and keystore location


To upgrade after changes to the I2P Atom extension:

$ . env/bin/activate
$ pip uninstall feedgen-i2p
$ pip install .



To write a news entry:

$ EDITOR=vim ./create_new_entry.sh

The highest-level heading that can be used is <h4>, but it looks bad in CSS, so
for now use <p><b>.

If it's an I2P release, edit data/releases.json as well.
Valid su3 map entries in releases.json are:

   torrent:     A single magnet link
   url:         A list of in-i2p http URLs, supported in I2P as of 1.6.0
   clearnet:    A list of non-i2p http URLs, not currently supported in I2P
   clearnetssl: A list of non-i2p https URLs, not currently supported in I2P


NOTE: Only the following XHTML entities are allowed in news entries.
Strict XHTML is required. This is enforced in NewsXMLParser.

    "a", "b", "br", "div", "i", "p", "span", "font", "blockquote", "hr",
    "del", "ins", "em", "strong", "mark", "sub", "sup", "tt", "code", "strike", "s", "u",
    "h4", "h5", "h6",
    "ol", "ul", "li", "dl", "dt", "dd",
    "table", "tr", "td", "th"

Please use .i2p links instead of clearnet links in news entries if possible.

**Important:** Validate your XHTML with
$ xmllint data/entries.html > /dev/null || echo FAIL

**WARNING:** *NEVER* push translations from here (tx push -t)! The strings will
*NOT* match, and *ALL* translations will get out-of-sync!

To push the new entry into translations:

$ tx push -s
$ tx pull --use-git-timestamps -a


To pull translations:

$ tx pull --use-git-timestamps -a


To build the feeds:

$ ./news.sh


Server requirements:

We recommend that the news server be run on its own
tunnels and website, not combined with anything else,
so the traffic and connection limits may be managed separately.

Server MUST send Last-Modified or Etag header, and respond correctly
to conditional headers in the request, so that unmodified
files are not re-downloaded and re-displayed in the router console.
For lighttpd, these headers are NOT set unless mime types are
configured for .su3 and .xml files; they are NOT configured by default.

For languages other than English, the router appends a ?lang=xx parameter
to the URL, where xx is two or more lower-case letters (language code)
possibly followed by an underscore and two or more upper-case letters (country code).
The server must map this request to the correct file, if available,
with fallback to a file that is available.


There are two supported hosting solutions:

1) lighttpd

Example rewrite rules for lighttpd to host the feeds:

    url.rewrite-repeat = (
        "^/news/news.atom.xml\?lang=([a-z]+(_[A-Za-z]+)?)" => "/news/news_$1.atom.xml",
        "^/news/news.su3\?lang=([a-z]+(_[A-Za-z]+)?)" => "/news/news_$1.su3",
    )
    url.rewrite-repeat-if-not-file = (
        "^/news/news_([a-z]+)_[A-Za-z]+.atom.xml" => "/news/news_$1.atom.xml",
        "^/news/news_([a-z]+)_[A-Za-z]+.su3" => "/news/news_$1.su3",
        "^/news/news_[a-z]+.atom.xml" => "/news/news.atom.xml",
        "^/news/news_[a-z]+.su3" => "/news/news.su3",
    )


2) flask

For an alternative implementation using an apache reverse proxy and flask,
see the newsxml-flask/ directory in the i2p.scripts branch in monotone
for the code and instructions.


To generate a new signed blocklist:

You must have router signing privileges (i.e. a certificate in $I2P/certificates/router)
for routers to verify the signature. If you do not have privileges, ask somebody that
does to generate it and check it in.
Generation requires I2P 0.9.27-12 or higher.

Before signing, create a symlink to the certificates directory in the
directory you are signing from, usually this will be the `i2p.newsxml` checkout.

        ln -s $HOME/i2p/certificates

Input file is blocklist.txt. Format:
One IPv4 or IPv6 address or base 64 router hash per line.
No host names or netmasks (e.g. /24) are allowed.
Comments start with # in column 1.
To unblock an address or hash blocked in a previous blocklist, prefix with !

Blocking/unblocking guidelines: Do not add blocks already in the release
blocklist (installer/resources/blocklist.txt in the source, or
$I2P/blocklist.txt in the installation directory).
Unblocks only work if blocked in a previous feed; they will not override
the release blocklist.

Example blocklist.txt:
# comment
1.2.3.4
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
!5.6.7.8

$ java -jar /path/to/routerconsole.jar blocklistentries [-p keystorepassword] /path/to/blocklist.txt /path/to/su3keystore.ks you@mail.i2p > data/blocklist.xml

Review output file to see if it looks right.
Don't forget to check in data/blocklist.xml.