doc/integration.texi

   1 @node Integration
   2 @unnumbered Integration with existing software
   3
   4 Here is some examples of how you can solve popular tasks with NNCP,
   5 making them store-and-forward friendly.
   6
   7 @menu
   8 * Postfix::
   9 * Web feeds: Feeds.
  10 * Web pages: WARCs.
  11 * BitTorrent and huge files: BitTorrent.
  12 * Downloading service: DownloadService.
  13 * Git::
  14 * Multimedia streaming: Multimedia.
  15 @end menu
  16
  17 @node Postfix
  18 @section Integration with Postfix
  19
  20 This section is taken from @url{http://www.postfix.org/nncp_README.html,
  21 Postfix and UUCP} manual and just replaces UUCP-related calls with NNCP
  22 ones.
  23
  24 @strong{Setting up a Postfix Internet to NNCP gateway}
  25
  26 Here is how to set up a machine that sits on the Internet and that forwards
  27 mail to a LAN that is connected via NNCP.
  28
  29 @itemize
  30
  31 @item You need an @ref{nncp-exec} program that extracts the sender
  32 address from mail that arrives via NNCP, and that feeds the mail into
  33 the Postfix @command{sendmail} command.
  34
  35 @item Define a @command{pipe(8)} based mail delivery transport for
  36 delivery via NNCP:
  37 @verbatim
  38 /usr/local/etc/postfix/master.cf:
  39 nncp      unix  -       n       n       -       -       pipe
  40           flags=F user=nncp argv=nncp-exec -quiet $nexthop sendmail $recipient
  41 @end verbatim
  42
  43 This runs the @command{nncp-exec} command to place outgoing mail into
  44 the NNCP queue after replacing @var{$nexthop} by the the receiving NNCP
  45 node and after replacing @var{$recipient} by the recipients. The
  46 @command{pipe(8)} delivery agent executes the @command{nncp-exec}
  47 command without assistance from the shell, so there are no problems with
  48 shell meta characters in command-line parameters.
  49
  50 @item Specify that mail for @emph{example.com}, should be delivered via
  51 NNCP, to a host named @emph{nncp-host}:
  52
  53 @verbatim
  54 /usr/local/etc/postfix/transport:
  55     example.com     nncp:nncp-host
  56     .example.com    nncp:nncp-host
  57 @end verbatim
  58
  59 See the @command{transport(5)} manual page for more details.
  60
  61 @item Execute the command @command{postmap /etc/postfix/transport}
  62 whenever you change the @file{transport} file.
  63
  64 @item Enable @file{transport} table lookups:
  65
  66 @verbatim
  67 /usr/local/etc/postfix/main.cf:
  68     transport_maps = hash:$config_directory/transport
  69 @end verbatim
  70
  71 @item Add @emph{example.com} to the list of domains that your site is
  72 willing to relay mail for.
  73
  74 @verbatim
  75 /usr/local/etc/postfix/main.cf:
  76     relay_domains = example.com ...other relay domains...
  77 @end verbatim
  78
  79 See the @option{relay_domains} configuration parameter description for
  80 details.
  81
  82 @item Execute the command @command{postfix reload} to make the changes
  83 effective.
  84
  85 @end itemize
  86
  87 @strong{Setting up a Postfix LAN to NNCP gateway}
  88
  89 Here is how to relay mail from a LAN via NNCP to the Internet.
  90
  91 @itemize
  92
  93 @item You need an @ref{nncp-exec} program that extracts the sender
  94 address from mail that arrives via NNCP, and that feeds the mail into
  95 the Postfix @command{sendmail} command.
  96
  97 @item Specify that all remote mail must be sent via the @command{nncp}
  98 mail transport to your NNCP gateway host, say, @emph{nncp-gateway}:
  99
 100 @verbatim
 101 /usr/local/etc/postfix/main.cf:
 102     relayhost = nncp-gateway
 103     default_transport = nncp
 104 @end verbatim
 105
 106 Postfix 2.0 and later also allows the following more succinct form:
 107
 108 @verbatim
 109 /usr/local/etc/postfix/main.cf:
 110     default_transport = nncp:nncp-gateway
 111 @end verbatim
 112
 113 @item Define a @command{pipe(8)} based message delivery transport for
 114 mail delivery via NNCP:
 115
 116 @verbatim
 117 /usr/local/etc/postfix/master.cf:
 118 nncp      unix  -       n       n       -       -       pipe
 119           flags=F user=nncp argv=nncp-exec -quiet $nexthop sendmail $recipient
 120 @end verbatim
 121
 122 This runs the @command{nncp-exec} command to place outgoing mail into
 123 the NNCP queue. It substitutes the hostname (@emph{nncp-gateway}, or
 124 whatever you specified) and the recipients before executing the command.
 125 The @command{nncp-exec} command is executed without assistance from the
 126 shell, so there are no problems with shell meta characters.
 127
 128 @item Execute the command @command{postfix reload} to make the changes
 129 effective.
 130
 131 @end itemize
 132
 133 @node Feeds
 134 @section Integration with Web feeds
 135
 136 RSS and Atom feeds could be collected using
 137 @url{https://github.com/wking/rss2email, rss2email} program. It
 138 converts all incoming feed entries to email messages. Read about how to
 139 integration @ref{Postfix} with email. @command{rss2email} could be run
 140 in a cron, to collect feeds without any user interaction. Also this
 141 program supports ETags and won't pollute the channel if remote server
 142 supports them too.
 143
 144 After installing @command{rss2email}, create configuration file:
 145 @verbatim
 146 % r2e new rss-robot@address.com
 147 @end verbatim
 148 and add feeds you want to retrieve:
 149 @verbatim
 150 % r2e add https://git.cypherpunks.ru/cgit.cgi/nncp.git/atom/?h=master
 151 @end verbatim
 152 and run the process:
 153 @verbatim
 154 % r2e run
 155 @end verbatim
 156
 157 @node WARCs
 158 @section Integration with Web pages
 159
 160 Simple HTML web page can be downloaded very easily for sending and
 161 viewing it offline after:
 162 @verbatim
 163 % wget http://www.example.com/page.html
 164 @end verbatim
 165
 166 But most web pages contain links to images, CSS and JavaScript files,
 167 required for complete rendering.
 168 @url{https://www.gnu.org/software/wget/, GNU Wget} supports that
 169 documents parsing and understanding page dependencies. You can download
 170 the whole page with dependencies the following way:
 171 @verbatim
 172 % wget \
 173     --page-requisites \
 174     --convert-links \
 175     --adjust-extension \
 176     --restrict-file-names=ascii \
 177     --span-hosts \
 178     --random-wait \
 179     --execute robots=off \
 180     http://www.example.com/page.html
 181 @end verbatim
 182 that will create @file{www.example.com} directory with all files
 183 necessary to view @file{page.html} web page. You can create single file
 184 compressed tarball with that directory and send it to remote node:
 185 @verbatim
 186 % tar cf - www.example.com | xz -9 |
 187     nncp-file - remote.node:www.example.com-page.tar.xz
 188 @end verbatim
 189
 190 But there are multi-paged articles, there are the whole interesting
 191 sites you want to get in a single package. You can mirror the whole web
 192 site by utilizing @command{wget}'s recursive feature:
 193 @verbatim
 194 % wget \
 195     --recursive \
 196     --timestamping \
 197     -l inf \
 198     --no-remove-listing \
 199     --no-parent \
 200     [...]
 201     http://www.example.com/
 202 @end verbatim
 203
 204 There is a standard for creating
 205 @url{https://en.wikipedia.org/wiki/Web_ARChive, Web ARChives}:
 206 @strong{WARC}. Fortunately again, @command{wget} supports it as an
 207 output format.
 208 @verbatim
 209 % wget \
 210     --warc-file www.example_com-$(date '+%Y%M%d%H%m%S') \
 211     --no-warc-compression \
 212     --no-warc-keep-log \
 213     [...]
 214     http://www.example.com/
 215 @end verbatim
 216 That command will create uncompressed @file{www.example_com-XXX.warc}
 217 web archive. By default, WARCs are compressed using
 218 @url{https://en.wikipedia.org/wiki/Gzip, gzip}, but, in example above,
 219 we have disabled it to compress with stronger @command{xz}, before
 220 sending via @command{nncp-file}.
 221
 222 There are plenty of software acting like HTTP proxy for your browser,
 223 allowing to view that WARC files. However you can extract files from
 224 that archive using @url{https://pypi.python.org/pypi/Warcat, warcat}
 225 utility, producing usual directory hierarchy:
 226 @verbatim
 227 % python3 -m warcat extract \
 228     www.example_com-XXX.warc \
 229     --output-dir www.example.com-XXX \
 230     --progress
 231 @end verbatim
 232
 233 @node BitTorrent
 234 @section BitTorrent and huge files
 235
 236 If dealing with @ref{Git}, @ref{Feeds, web feeds} and @ref{Multimedia,
 237 multimedia} goes relatively fast, then BitTorrent and huge files
 238 consumes much time. You can not wait for downloads finish, but want to
 239 queue them after.
 240
 241 @url{http://aria2.github.io/, aria2} multi-protocol download utility
 242 could be used for solving that issue conveniently. It supports HTTP,
 243 HTTPS, FTP, SFTP and BitTorrent protocols, together with
 244 @url{http://tools.ietf.org/html/rfc5854, Metalink} format. BitTorrent
 245 support is fully-featured: UDP trackers, DHT, PEX, encryption, magnet
 246 URIs, Web-seeding, selective downloads, LPD. @command{aria2} can
 247 accelerate HTTP*/*FTP downloads by segmented multiple parallel
 248 connections.
 249
 250 You can queue you files after they are completely downloaded:
 251 @verbatim
 252 % cat send-downloaded.sh
 253 #!/bin/sh
 254
 255 if [ "$2" -eq 0 ]; then
 256     # This could be downloaded .torrent file itself
 257     exit 0
 258 fi
 259
 260 if [ "$2" -gt 1 ]; then
 261     # This is directory downloaded with BitTorrent
 262     wholedir="$(dirname "$3")"
 263     name=$(basename "$wholedir")
 264     cd "$wholedir"/..
 265     tartmp=$(mktemp ./finished.XXXXXX)
 266     tar cf $tartmp "$name"
 267     nncp-file -chunked $(( 1024 * 100 )) $tartmp remote:"$name".tar
 268     rm $tartmp
 269 else
 270     nncp-file -chunked $(( 1024 * 100 )) "$3" remote:
 271 fi
 272
 273 % aria2c \
 274     --on-download-complete send-downloaded.sh \
 275     http://example.org/file.iso \
 276     http://example.org/file.iso.asc
 277 % aria2c \
 278     --on-bt-download-complete send-downloaded.sh \
 279     http://example.org/file.torrent
 280 @end verbatim
 281
 282 Also you can prepare
 283 @url{http://aria2.github.io/manual/en/html/aria2c.html#files, input file}
 284 with the jobs you want to download:
 285 @verbatim
 286 % cat jobs
 287 http://www.nncpgo.org/download/nncp-0.11.tar.xz
 288     out=nncp.txz
 289 http://www.nncpgo.org/download/nncp-0.11.tar.xz.sig
 290     out=nncp.txz.sig
 291 % aria2c \
 292     --on-download-complete send-downloaded.sh \
 293     --input-file jobs
 294 @end verbatim
 295 and all that downloaded (@file{nncp.txz}, @file{nncp.txz.sig}) files
 296 will be sent to @file{remote.node} when finished.
 297
 298 @node DownloadService
 299 @section Downloading service
 300
 301 Previous sections tell about manual downloading and sending results to
 302 remote node. But one wish to remotely initiate downloading. That can be
 303 easily solved with @ref{CfgExec, exec} handles.
 304
 305 @verbatim
 306 exec:
 307   warcer: ["/bin/sh", "/path/to/warcer.sh"]
 308   wgeter: ["/bin/sh", "/path/to/wgeter.sh"]
 309   aria2c: [
 310     "/usr/local/bin/aria2c",
 311     "--on-download-complete", "send-downloaded.sh",
 312     "--on-bt-download-complete", "send-downloaded.sh"
 313   ]
 314 @end verbatim
 315
 316 @file{warcer.sh} contents:
 317
 318 @verbatim
 319 #!/bin/sh -ex
 320
 321 user_agent="Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US) AppleWebKit/533.20.25 (KHTML, like Gecko) Version/5.0.4 Safari/533.20.27"
 322
 323 name="$1"
 324 read cmdline
 325
 326 tmp=$(mktemp -d)
 327 cd $tmp
 328 warc_name=$name-$(date '+%Y%M%d%H%m%S')
 329 wget \
 330     --page-requisites \
 331     --convert-links \
 332     --adjust-extension \
 333     --restrict-file-names=ascii \
 334     --span-hosts \
 335     --random-wait \
 336     --execute robots=off \
 337     --user-agent "$user_agent" \
 338     --reject '*.woff*,*.ttf,*.eot,*.js' \
 339     --tries 10 \
 340     --warc-file $warc_name \
 341     --no-warc-compression \
 342     --no-warc-keep-log \
 343     $cmdline || :
 344 xz -9 "$warc_name".warc
 345 nncp-file -nice $NNCP_NICE "$warc_name".warc.xz $NNCP_SENDER:
 346 rm -r $tmp
 347 @end verbatim
 348
 349 @file{wgeter.sh} contents:
 350
 351 @verbatim
 352 #!/bin/sh -ex
 353
 354 name="$1"
 355 read cmdline
 356 tmp=$(mktemp)
 357 wget --output-document=$tmp $cmdline
 358 xz -9 $tmp
 359 nncp-file -nice $NNCP_NICE $tmp.xz $NNCP_SENDER:$name.xz
 360 rm $tmp.xz
 361 @end verbatim
 362
 363 Now you can queue that node to send you some website's page, file or
 364 BitTorrents:
 365
 366 @verbatim
 367 % echo http://www.nncpgo.org/Postfix.html |
 368     nncp-exec remote.node warcer postfix-whole-page
 369 % echo http://www.nncpgo.org/Postfix.html |
 370     nncp-exec remote.node wgeter postfix-html-page
 371 % echo \
 372     http://www.nncpgo.org/download/nncp-0.11.tar.xz
 373     http://www.nncpgo.org/download/nncp-0.11.tar.xz.sig |
 374     nncp-exec remote.node aria2c
 375 @end verbatim
 376
 377 @node Git
 378 @section Integration with Git
 379
 380 @url{https://git-scm.com/, Git} version control system already has all
 381 necessary tools for store-and-forward networking.
 382 @url{https://git-scm.com/docs/git-bundle, git-bundle} command is
 383 everything you need.
 384
 385 Use it to create bundles containing all required blobs/trees/commits and tags:
 386 @verbatim
 387 % git bundle create repo-initial.bundle master --tags --branches
 388 % git tag -f last-bundle
 389 % nncp-file repo-initial.bundle remote.node:repo-$(date % '+%Y%M%d%H%m%S').bundle
 390 @end verbatim
 391
 392 Do usual working with the Git: commit, add, branch, checkout, etc. When
 393 you decide to queue your changes for sending, create diff-ed bundle and
 394 transfer them:
 395 @verbatim
 396 % git bundle create repo-$(date '+%Y%M%d%H%m%S').bundle last-bundle..master
 397 or maybe
 398 % git bundle create repo-$(date '+%Y%M%d').bundle --since=10.days master
 399 @end verbatim
 400
 401 Received bundle on remote machine acts like usual remote:
 402 @verbatim
 403 % git clone -b master repo-XXX.bundle
 404 @end verbatim
 405 overwrite @file{repo.bundle} file with newer bundles you retrieve and
 406 fetch all required branches and commits:
 407 @verbatim
 408 % git pull # assuming that origin remote points to repo.bundle
 409 % git fetch repo.bundle master:localRef
 410 % git ls-remote repo.bundle
 411 @end verbatim
 412
 413 Bundles are also useful when cloning huge repositories (like Linux has).
 414 Git's native protocol does not support any kind of interrupted download
 415 resuming, so you will start from the beginning if connection is lost.
 416 Bundles, being an ordinary files, can be downloaded with native
 417 HTTP/FTP/NNCP resuming capabilities. After you fetch repository via the
 418 bundle, you can add an ordinary @file{git://} remote and fetch the
 419 difference.
 420
 421 @node Multimedia
 422 @section Integration with multimedia streaming
 423
 424 Many video and audio streams could be downloaded using
 425 @url{http://yt-dl.org/, youtube-dl} program.
 426 @url{https://rg3.github.io/youtube-dl/supportedsites.html, Look} how
 427 many of them are supported, including @emph{Dailymotion}, @emph{Vimeo}
 428 and @emph{YouTube}.
 429
 430 When you multimedia becomes an ordinary file, you can transfer it easily.
 431 @verbatim
 432 % youtube-dl \
 433     --exec 'nncp-file {} remote.node:' \
 434     'https://www.youtube.com/watch?list=PLd2Cw8x5CytxPAEBwzilrhQUHt_UN10FJ'
 435 @end verbatim