DRDC Document Number: DRDC-RDDC-2016-N036 LTTng: The Linux Trace Toolkit Next Generation A Comprehensive User's Guide (version 2.3 edition) Daniel U. Thibault, DRDC Valcartier Research Centre The contents are published as open-access documentation distributed under the terms of the Creative Commons Attribution 4.0 International Public License (CC-BY 4.0, http://creativecommons.org/licenses/by/4.0), which permits unrestricted use, distribution, and reproduction in any medium, provided the original author and source are credited. Defence Research and Development Canada External Literature DRDC-RDDC-2016-N036 June 2016 © Her Majesty the Queen in Right of Canada, as represented by the Minister of National Defence, 2016 © Sa Majesté la Reine (en droit du Canada), telle que représentée par le ministre de la Défense nationale, 2016 IMPORTANT INFORMATIVE STATEMENTS Work conducted for project 15bl, HeLP-CCS: Host-Level Protection of Critical Computerized Systems Template in use: SR Advanced (2010) Template_EN (2015-11-05).dotm © Her Majesty the Queen in Right of Canada, as represented by the Minister of National Defence, 2016. LTTng: The Linux Trace Toolkit Next Generation: A Comprehensivve User's Guide (version 2.3 edition) is made available under the Creative Commons Attribution 4.0 Innternational Public License (CC-BY 4.0, http://creativecommons.org/licenses/by/4.0). © Sa Majesté la Reine (en droit du Canada), telle que représentée par le ministre de la Défense nationale, 2016. LTTng: The Linux Trace Toolkit Next Generation: A Comprehensive User's Guide (version 2.3 edition) est rendu disponible sous la licence publique Creative Commons Attribution 4.0 International (CC-BY 4.0, http://creativecommons.org/licenses/by/4.0/deed.fr). Abstract The Linux Trace Toolkit Next Generation (LTTng) software tracer was thoroughly documented from a user’s perspective. The behaviour of each command was tested for a wide range of input parameter values, installation scripts were written and tested, and a variety of demonstration use cases created and tested. A number of bugs were documented as a result (ranging from “simply broken” to “what exactly are we trying to do here?”) which are being addressed as time passes and the project keeps advancing in capability, reliability, and ease-of-use. Whereas the companion LTTng Quick Start Guide assumed the simplest installation and use scenario, the LTTng Comprehensive User’s Guide delves into the nitty-gritty of using LTTng in all sorts of ways, leaving no option undocumented and giving detailed, step-by-step instructions on how to instrument anything (applications, libraries, kernel modules, even the kernel itself) for use with LTTng. Significance to defence and security The Linux Trace Toolkit Next Generation (LTTng) offers reliable, low-impact, high-resolution, system-wide, dynamically adaptable, near-real-time tracing of Linux systems. Being able to observe what goes on within the operating system and any applications running on it is an essential prerequisite for the cyber security of governmental and military computer systems of all scales. As the LTTng project has now reached a reasonable level of maturity and can be used in production contexts, it was felt necessary to create a document detailing in practical terms how to deploy, use, and extend it. Large parts of this document have already been used to create the LTTng on-line documentation (http://lttng.org/docs/#); this publication can only make LTTng more accessible to all interested parties. DRDC-RDDC-2016-R9999 i Résumé Le traceur logiciel Linux Trace Toolkit Next Generation (LTTng) a été documenté exhaustivement du point de vue de l’utilisateur. Le comportement de chaque commande a été testé pour une grande variété de valeurs de paramètres, des scripts d’installation ont été écrits et testés, et bon nombre de démonstrations utilitaires créées et testées. Une quantité de bogues ont été documentées par conséquent (allant de « c’est cassé » à « qu’est-ce qu’on essaie d’accomplir ici ? »), lesquelles succombent progressivement au passage du temps tandis que le projet continue de s’améliorer en capacité, fiabilité, et facilité d’utilisation. Alors que le document complémentaire LTTng Quick Start Guide supposait le cas le plus simple d’installation et d’utilisation, le LTTng Comprehensive User’s Guide plonge dans le détail de l’utilisation de LTTng de toutes sortes de façons, ne laissant aucune option sans documentation et donnant des instructions étape-par-étape et détaillées expliquant comment instrumenter n’importe quoi (applications, bibliothèques, modules du noyau, et le noyau lui-même) aux fins de LTTng. Importance pour la défense et la sécurité Le traceur Linux Trace Toolkit Next Generation (LTTng) est en mesure de tracer les systèmes Linux en temps presque réel de façon flexible (dynamiquement adaptable), universelle, détaillée, fiable et économe en coût de performance. Être capable d’observer ce qui se passe à l’intérieur du système d’exploitation et de ses applications est une condition sine qua non de la cyber sécurité des systèmes informatiques gouvernementaux et militaires de toute échelle. Comme le projet LTTng a atteint un niveau raisonnable de maturité et peut être utilisé dans des contextes de production, il nous a semblé nécessaire de créer un document détaillant en termes pratiques comment le déployer, l’utiliser et l’augmenter. Une large part de ce document a déjà été utilisée pour créer la documentation en ligne de LTTng (http://lttng.org/docs/#); cette publication ne peut que rendre LTTng encore plus accessible aux parties intéressées. ii DRDC-RDDC-2016-R9999 Table of contents Abstract ............................................................................................................................................ i Significance to defence and security ................................................................................................ i Résumé ............................................................................................................................................ ii Importance pour la défense et la sécurité ........................................................................................ ii Table of contents ............................................................................................................................ iii List of figures ................................................................................................................................. ix List of tables ................................................................................................................................... xi Acknowledgements ....................................................................................................................... xii 1 Introduction ............................................................................................................................... 1 1.1 The LTTng software tracer — Basic concepts ................................................................ 2 1.2 Scope of this document.................................................................................................... 3 1.3 Quick references .............................................................................................................. 4 1.4 The content of the DVD-ROM ........................................................................................ 5 1.4.1 VirtualBox virtual machine .............................................................................. 5 1.4.2 Software repository ........................................................................................... 6 1.5 How to read this document .............................................................................................. 6 1.6 Caveats ............................................................................................................................ 7 2 LTTng architecture, basic configuration and controls .............................................................. 9 2.1 LTTng components ......................................................................................................... 9 2.1.1 The LTTng session daemon(s) (lttng-sessiond) .................................. 10 2.1.2 The LTTng consumer daemon(s) (lttng-consumerd) ............................ 12 2.1.3 The LTTng command-line and custom control interfaces .............................. 12 2.1.4 The liburcu library ..................................................................................... 13 2.1.5 The liblttng-ust library ......................................................................... 13 2.1.6 The liblttng-ust-ctl library ............................................................... 13 2.1.7 The LTTng kernel modules ............................................................................ 13 2.1.8 The LTTng relay daemon (lttng-relayd) ............................................... 13 2.1.9 babeltrace and its library ......................................................................... 14 2.1.10 LTTV .............................................................................................................. 14 2.2 Tracing sessions and traces ............................................................................................ 14 2.2.1 Domains and the tracing group ....................................................................... 16 2.3 Flow of control and data ...............................................................................................