Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/iblech/sshlatex

A collection of hacks to efficiently run LaTeX via ssh
https://github.com/iblech/sshlatex

autocompile latex ssh

Last synced: about 1 month ago
JSON representation

A collection of hacks to efficiently run LaTeX via ssh

Awesome Lists containing this project

README 

        
# sshlatex: A collection of hacks to efficiently run LaTeX via ssh



Tired of long LaTeX compile times on your old, slow computer? Do you want a

tool which monitors your source file for changes, copies it to a fast remote

server, runs LaTeX there, and downloads the resulting PDF file?



Then look no further. Actually, you should; this repository is a collection of

horrible hacks to make this possible. They work for me. Highlights are that

sshlatex prestarts LaTeX on the server with the previous run's preamble to

preload all those required LaTeX packages and that it starts streaming the PDF

file before LaTeX finishes creating it.



[![demo](asciicast.gif)](https://asciinema.org/a/36010?autoplay=1)



## Usage



1. Run `sshlatex ssh.example.org foo.tex` in the background. Just as with

   `pdflatex`, you may drop the extension `.tex` if you want to.

2. Work on your file `foo.tex`.

3. Enjoy an updated PDF each time you save your changes.



Optionally, put a program `beepy` in your `$PATH` (or change the corresponding

line in the source code) to audibly inform you of a completed run. Useful for

when you're switching virtual desktops and don't see the output of sshlatex.



* See below for when you don't have passphrase-less login to the remote end set up.



* Tip for when you're using a lightweight PDF viewer which doesn't auto-reload on

  changes: Put something like the following in your `beepy` program.



  ```shell

  # Send the "r" key to all running mupdf instances.

  for i in `xdotool search --class mupdf`; do

      xdotool key --window $i r

  done

  ```



* Use the `draft` option in your LaTeX `\documentclass` command to further

  speed up compilation. For instance, this option disables the

  [microtype](http://texdoc.net/texmf-dist/doc/latex/microtype/microtype.pdf)

  package.



## Features



* No installation is necessary, neither on the remote host nor on the local side.



* Images, sources, bibliography lists, and local class and style files

  (for instance embedded using `\includegraphics`, `\input`, or `\include`) are

  automatically copied to the compile server. Using a crude heuristic, this

  even extends to files included by custom commands.



* Even before the source file is changed, LaTeX gets already started on the

  remote host with the preamble of the previous run. This way all the required

  packages are already loaded when the new version is ready to be compiled,

  shaving off a couple of hundreds of milliseconds.



  If you want more parts of your document to be precompiled, not only the

  preamble, then put a commented `% \begin{document}` declaration between the

  part which should be precompiled and the part which changes often. LaTeX will

  ignore this declaration, but sshlatex will use it to determine where to split

  the file.



* Downloading the resulting PDF file starts before each run of `pdflatex`

  has finished. Since `pdflatex` does not simply append to the output file, but

  seeks and overwrites earlier parts, sshlatex is prepared to transfer some

  blocks multiple times if necessary. This is still faster than waiting for

  `pdflatex` to finish and then doing a proper `rsync`.



* Temporary files on the server are properly cleaned up on `^C`.



* Filenames with special characters in them are supported.



* Proper care is taken to ensure that shell commands directed at the remote

  host are interpreted by the bash, even if a different shell is the default.



## Dependencies



Aside from standard Linux tools and Perl 5 (included in the base installation of

practically any Linux distribution), sshlatex has no dependencies on the local

host and only LaTeX on the remote host. If inotifywait from the inotify-tools

package is installed on the local side, sshlatex will use it instead of

resorting to polling for detecting changes in the source files.



You should use the multiplexing capabilities of ssh, so that new connections

are piggybacked over an already established connection avoiding the

time-consuming TCP and cryptography handshake. Add the following two lines to

your local `~/.ssh/config` and open a separate SSH connection before you start

sshlatex.



    ControlMaster auto

    ControlPath ~/.ssh/control:%h:%p:%r



_If you don't have passphrase-less login to the remote end set up, ssh multiplexing is

not only nice to have, but absolutely crucial, as else you'd be forced to enter

login credentials each time you change the LaTeX source._



## Purely local usage



Because of the prestart feature, sshlatex can even make sense if you run it

purely locally. Call `sshlatex localhost foo.tex`. Invoked with the special

hostname `localhost`, sshlatex avoids actually calling ssh. Therefore this

command will work even if you don't have an ssh server running on localhost.



## Security considerations



Essentially, don't run sshlatex on untrusted files or with untrusted servers.

Specifically:



* sshlatex places several files, including LaTeX source files, in a temporary

  directory on the server side. This might leak data or metadata (for instance

  on when you are working on your LaTeX documents) to the administrator or

  other users on the server. You can change the location of the temporary

  directory by arranging an appropriate value of `$TMPDIR` on the remote end.

* sshlatex happily uploads any included files to the server, even files

  outside the base directory (as for instance prompted by a command like

  `\includegraphics{/etc/passwd}` in the LaTeX source file).

* When downloading the resulting PDF file, sshlatex accepts any data from the

  server. This could be exploited by an attacker for a denial of service

  attack by filling the memory or disk.

* [The usual problems with compiling](https://0day.work/hacking-with-latex/)

  [untrusted LaTeX source files apply.](https://scumjr.github.io/2016/11/28/pwning-coworkers-thanks-to-latex/)



## Shortcomings



* Written in haste, will contain bugs. Is a grave assortment of hacks, the

  least of which is using the `LC_*` environment variables to pass data to the

  remote host.

* Not customizable.

* Doesn't support fancy reruns of LaTeX for making sure that references are

  correct and so on. This tool is for rapidly iterating.



## License



sshlatex is dual-licensed, meaning that you can (and are invited to) use,

redistribute and modify it under the terms of either:



1. The GNU General Public License (GPL), version 3 or (at your option) any

   later version published by the Free Software Foundation.

2. The LaTeX Project Public License (LPPL), version 1.3c or (at your option)

   any later version published by the LaTeX3 project.