Skip to content

How the data flows

This page describes where a document goes during a conversion and which files stay afterwards. It matters if your documents are confidential. The flow changed in 2.1.0, so there is one section for each line. See Versions.

Short version

The document stays on your server. LibreOffice runs as a local process. The module makes no network call.

2.1.x

Nothing is reachable by URL while a conversion runs, and a file becomes permanent only when a saved entity uses it.

  1. Upload. The editor uploads the document in the form. It is saved as a temporary managed file in temporary://<folder>/<uuid>/, one folder for each conversion. <folder> is the Folder name from Basic Settings. Nothing is written under public:// at this stage.
  2. Conversion. PHP starts soffice with proc_open, without a shell. The process gets the conversion folder as output directory and as HOME, and its own LibreOffice profile inside it (lo-profile). Two conversions at the same time do not share a profile.
  3. Timeout. If the process runs longer than the timeout, it receives SIGTERM, then SIGKILL after a short wait.
  4. Result. The module reads the single .html file in the folder, then runs its processing chain. See The widget.
  5. Images. Images used in the HTML are copied into temporary managed files in the image upload directory. The editor module makes them permanent when the text is saved.
  6. Source document. If a source file field is set, the document is moved to the upload directory of that field and stays temporary until the node is saved. Otherwise it is deleted.
  7. Cleanup. The conversion folder is deleted when the conversion ends, with success or with an error. Permanent files and files in use inside it are kept.

Drupal 12 and an empty folder

Drupal 12 creates the upload directory of a file element each time the form is built. An empty folder can reappear after the cleanup. The module cron removes empty folders with the old ones.

The life of a file

The rule is that a file is permanent only when a saved entity uses it, and the cron of this module touches only the working folder.

Case Where it is State Who removes it
Kept and saved Directory of the source file field Permanent, in use Nobody, it is never touched
Kept but abandoned (the form was left without saving) Directory of the source file field Temporary The cron of core, after temporary_maximum_age
In transit (the upload, the HTML, the discarded images, the LibreOffice profile) Conversion folder Temporary The end of the conversion, or the cron of this module after six hours
Inserted image Image upload directory Same as the document Same as the document

temporary_maximum_age is a setting of system.file, 6 hours by default. The cron of core removes temporary files older than that.

Cron

The cron task of the module does two things:

  • It deletes the conversion folders untouched for six hours, with their files. Permanent files and files in use stay. It does not touch folders with a similar name, such as doc_to_html_other.
  • It deletes temporary file entities of the working folder whose file is gone.

It never looks outside the working folder. The files in the directories of your file fields and of the images are not its business. drush dth:clean runs the first task, see Drush commands.

Cluster note

The upload and the conversion use temporary://. On several servers that share a site, the temporary directory must be shared too, otherwise the server that converts may not see the upload.

2.0.x

2.0.x can lose files and shows them by URL

The files of 2.0.x live in a public folder, and its cleanup deletes more than it should. If you run Drupal 10, 11.0 or 11.1 you must stay on 2.0.x: use 2.0.2 or later, and never 2.0.0 or 2.0.1. See Versions.

  1. Upload. The document is saved in public://<folder>, by default public://doc_to_html. This is a public location, so the upload and the converted HTML can be opened by URL until the cleanup removes them.
  2. Conversion. soffice writes the HTML next to the upload, in the same folder. All conversions share one folder and one LibreOffice profile.
  3. Source document. If a source file field is set, the file is made permanent and left where it is, in the same public folder.
  4. Cleanup. The cron and the cleanup after every conversion delete the managed files of the folder.

Up to 2.0.1 the cleanup deleted every managed file whose address started with the folder, permanent or not, in use or not. That includes the documents saved in the source file field, and the files of other users who had just uploaded. The match was a prefix without a slash, so doc_to_html_other was cleaned too. Unmanaged files with the extensions html, doc, docx, odt, rtf and pptx were deleted as well.

2.0.2 does not touch permanent files or files in use.

Logs

If LibreOffice fails, its output goes to the Drupal log, shortened. The editor sees a generic message. The full command is not shown to the user.

Network

The module does not call any external service. LibreOffice itself runs in headless mode and does not need a network. If your servers block outgoing traffic, nothing changes.

What leaves the server

The HTML you save in a node and the images in the image upload directory become part of your site. The original document leaves the temporary area only if you configure a source file field.