A REAL-WORLD Companion CD includes a prototype G U I D E T O appliance—a home BUILDING LINUX LINUXLINUX APPLIANCEAPPLIANCE alarm system—that supports APPLIANCES the book’s lessons. APPLIANCES CD Inside DESIGNDESIGN A HANDS-ON GUIDE T O BUILDING LINUX APPLIANCES Modern appliances are complex machines with Learn to: processors, operating systems, and application software. P C ESIGN G I S DE NCE A I PPL A X U N I L
• Separate your user interfaces from your daemons N G I S DE NCE A I PPL A X U N I L While there are books that will tell you how to run Linux BOB SMITH, JOHN HARDIN, GRAHAM PHILLIPS, AND BILL PIERCE on embedded hardware, and books on how to build • Give user interfaces run time access to configuration, a Linux application, Linux Appliance Design is the first status, and statistics book to demonstrate how to merge the two and create • Add professional network management capabilities to a Linux appliance. You’ll see for yourself why Linux is your application the embedded operating system of choice for low-cost development and a fast time to market. • Use SNMP and build a MIB
Linux Appliance Design shows how to build better • Build a web-based appliance interface appliances—appliances with more types of interfaces, • Build a command line interface (CLI) more dynamic interfaces, and better debugged inter- faces. You’ll learn how to build backend daemons, • Build a framebuffer interface with an infrared control handle asynchronous events, and connect various user as input interfaces (including web, framebuffers, infrared control, • Manage logs and alarms on an appliance SNMP, and front panels) to these processes for remote configuration and control. Linux Appliance Design ABOUT THE AUTHORS also introduces the Run-Time Access library, which Bob Smith, John Hardin, Graham Phillips, and Bill Pierce provides a uniform mechanism for user interfaces to have experience in embedded systems, commercial Linux communicate with daemons. and BSD appliances, network management systems, and designing software solutions for business problems. D N A , S P I L I H P , N I D R A H E C R E I P , H T I M S
THE FINEST IN GEEK ENTERTAINMENT ™ $59.95 ($74.95 CDN) OPERATING SYSTEMS/LINUX OPERATING IN: SHELVE www.nostarch.com ®
“I LAY FLAT.” ® This book uses RepKover —a durable binding that won’t snap shut. ®
LINUX APPLIANCE DESIGN
LINUX APPLIANCE DESIGN
A Hands-On Guide to Building Linux Appliances
by Bob Smith, John Hardin, Graham Phillips, and Bill Pierce
®
San Francisco lad_TITLE_COPY.fm Page iv Thursday, March 15, 2007 2:38 PM
LINUX APPLIANCE DESIGN. Copyright © 2007 by Bob Smith, John Hardin, Graham Phillips, and Bill Pierce.
All “Tux’s Workshop” illustrations © 2006 by Jon Colton.
All rights reserved. No part of this work may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or by any information storage or retrieval system, without the prior written permission of the copyright owner and the publisher.
Printed on recycled paper in the United States of America
11 10 09 08 07 1 2 3 4 5 6 7 8 9
ISBN-10: 1-59327-140-9 ISBN-13: 978-1-59327-140-4
Publisher: William Pollock Production Editor: Elizabeth Campbell Cover and Interior Design: Octopod Studios Developmental Editor: William Pollock Technical Reviewer: Bob Lynch Copyeditor: Megan Dunchak Compositor: Riley Hoffman Proofreader: Publication Services, Inc. Indexer: Publication Services, Inc.
For information on book distributors or translations, please contact No Starch Press, Inc. directly:
No Starch Press, Inc. 555 De Haro Street, Suite 250, San Francisco, CA 94107 phone: 415.863.9900; fax: 415.863.9950; [email protected]; www.nostarch.com
Library of Congress Cataloging-in-Publication Data
Linux appliance design : a hands-on guide to building linux appliances / Bob Smith ... [et al.]. p. cm. Includes index. ISBN-13: 978-1-59327-140-4 ISBN-10: 1-59327-140-9 1. Linux. 2. Application software--Development. 3. Electric apparatus and appliances--Design and construction. I. Smith, Robert W. (Robert William), 1952- QA76.76.O63L545115 2007 005.3--dc22 2006020778
No Starch Press and the No Starch Press logo are registered trademarks of No Starch Press, Inc. Other product and company names mentioned herein may be the trademarks of their respective owners. Rather than use a trademark symbol with every occurrence of a trademarked name, we are using the names only in an editorial fashion and to the benefit of the trademark owner, with no intention of infringement of the trademark.
The information in this book is distributed on an “As Is” basis, without warranty. While every precaution has been taken in the preparation of this work, neither the author nor No Starch Press, Inc. shall have any liability to any person or entity with respect to any loss or damage caused or alleged to be caused directly or indirectly by the information contained in it. BRIEF CONTENTS
Acknowledgments ...... xv
Introduction ...... xvii
Chapter 1: Appliance Architecture ...... 1
Chapter 2: Managing Daemons...... 7
Chapter 3: Using Run-Time Access ...... 19
Chapter 4: Building and Securing Daemons ...... 43
Chapter 5: The Laddie Alarm System: A Sample Appliance...... 61
Chapter 6: Logging ...... 77
Chapter 7: Laddie Event Handling...... 91
Chapter 8: Designing a Web Interface ...... 105
Chapter 9: Designing a Command Line Interface ...... 135
Chapter 10: Building a Front Panel Interface ...... 147
Chapter 11: Designing a Framebuffer Interface...... 169
Chapter 12: Infrared Remote Control...... 197
Chapter 13: Hands-on Introduction to SNMP...... 223 Chapter 14: Designing an SNMP MIB ...... 243
Chapter 15: Implementing Your SNMP MIB...... 261
Appendix A: RTA Reference ...... 289
Appendix B: Review of SNMP ...... 309
Appendix C: Installing a Framebuffer Device Driver...... 325
Appendix D: A DB-to-File Utility...... 331
Appendix E: The Laddie Appliance Bootable CD ...... 337
Index ...... 345
vi Brief Contents CONTENTS IN DETAIL
ACKNOWLEDGMENTS xv
INTRODUCTION xvii What This Book Is About ...... xviii What This Book Is Not About ...... xviii Who Should Read This Book ...... xix Why Use Linux? ...... xix Availability of Source Code ...... xix Range of Hardware Supported ...... xix Availability of Linux Developers ...... xix Reliability ...... xx Quality Compilers ...... xx Good Documentation ...... xx Existing Software Packages ...... xx Low Development Cost ...... xx No Licensing Fees for Deployment ...... xx Security ...... xxi Linux Appliance Design ...... xxi
1 APPLIANCE ARCHITECTURE 1 UIs and Daemons ...... 2 Daemons ...... 2 User Interfaces ...... 3 Interprocess Communication ...... 4 The Architecture of the Laddie Appliance ...... 5 Summary ...... 5
2 MANAGING DAEMONS 7 Common Approaches to Managing Daemons ...... 8 File-Based Management ...... 8 A Daemon-Based Web Interface ...... 9 An All-in-One Approach ...... 10 Control and Status Protocols ...... 11 Requirements for a Control and Status Protocol ...... 12 Common Control and Status Protocols ...... 13 Summary ...... 18
3 USING RUN-TIME ACCESS 19 RTA Appliance Architecture ...... 19 RTA Daemon Architecture ...... 20 Telling RTA About Your Columns and Tables ...... 21 Columns ...... 22 Tables ...... 24 Building Your First RTA Program ...... 26 Defining the Problem ...... 26 Reviewing the Code ...... 26 Installing RTA ...... 31 Building and Linking ...... 32 Testing ...... 32 A Little SQL ...... 34 SELECT ...... 35 UPDATE ...... 35 WHERE ...... 36 LIMIT ...... 36 Introduction to RTA’s Built-in Tables ...... 37 rta_dbg ...... 37 rta_stat ...... 37 rta_tables ...... 38 rta_columns ...... 38 The RTA Table Editor ...... 38 Summary ...... 41
4 BUILDING AND SECURING DAEMONS 43 How to Build a Daemon ...... 44 Load the Daemon’s Configuration ...... 44 Go into the Background ...... 45 Become the Process and Session Leader ...... 46 Set the Working Directory ...... 47 Redirect stdin, stdout, and stderr ...... 47 Set Up Logging ...... 48 Set Group and User IDs ...... 49 Check for a pidfile ...... 50 Set the umask ...... 52 Set Up Signal Handlers ...... 52 How to Secure a Daemon ...... 53 Designing a Secure Daemon ...... 54 Write a Secure Daemon ...... 55 Limit Damage in Case of a Breach ...... 57 A Prototype Daemon ...... 59 Summary ...... 60 Further Reading ...... 60
5 THE LADDIE ALARM SYSTEM: A SAMPLE APPLIANCE 61 Introduction to Alarm Systems ...... 62 Sensors ...... 62 Enabling a Zone ...... 64
viii Contents in Detail A Functional Specification for Laddie ...... 64 ladd’s Configuration and Status ...... 65 ladd’s Alarm Handling ...... 67 Laddie’s Hardware Design ...... 68 Laddie’s Software Design ...... 69 The appInit() Callback Subroutine ...... 70 The poll_timeout() Callback Subroutine ...... 71 The user_update() Callback Subroutine ...... 73 Building and Testing ladd ...... 74 Summary ...... 76
6 LOGGING 77 Do You Need Logging? ...... 77 Architecture of a Logging System ...... 78 Message Sources ...... 78 Message Routing ...... 80 Message Destinations ...... 80 syslog ...... 82 syslog Architecture ...... 82 Using syslog ...... 83 The syslog Protocol ...... 84 Using the syslogd Daemon ...... 85 Limitations, Advantages, and Alternatives to syslogd ...... 86 On-Demand Logging ...... 87 Summary ...... 89
7 LADDIE EVENT HANDLING 91 Rationale for a New Event-Handling System ...... 92 Features and Capabilities of logmuxd ...... 93 Configuring logmuxd ...... 94 logmuxd Sources ...... 94 logmuxd Filters and Rewriting ...... 95 logmuxd Destinations ...... 97 Examples Using logmuxd ...... 98 Example 1: A logmuxd Demonstration ...... 98 Example 2: logmuxd and Accepted TCP Connections ...... 98 Example 3: logmuxd and SNMP Traps ...... 102 Summary ...... 104
8 DESIGNING A WEB INTERFACE 105 Web Basics ...... 106 DNS and TCP ...... 107 The Webserver ...... 107 CGI ...... 107
Contents in Detail ix JavaScript ...... 107 Evolving Technologies ...... 107 Establishing Requirements ...... 108 Choosing a Webserver ...... 108 Choices ...... 108 Use PHP ...... 109 Case Study: Linksys WRT54G Wireless Router ...... 109 Case Study: The TUX Webserver ...... 110 Comparison of Webservers ...... 110 UI Design ...... 114 Menu System ...... 114 Dialog Boxes ...... 115 Error Messages ...... 115 Improving Responsiveness with Ajax ...... 117 Implementation ...... 118 Interfacing with the Daemons ...... 119 Alarm Status Page ...... 121 Alarm Setup Page ...... 122 Page Layout and Menu System ...... 123 Webserver Independence ...... 124 Asynchronous Updates Using Ajax ...... 125 Improving Our Design ...... 131 Resources ...... 132 Summary ...... 133
9 DESIGNING A COMMAND LINE INTERFACE 135 Why You Need a CLI ...... 136 Security ...... 136 Availability ...... 136 Bandwidth ...... 137 Scriptability ...... 137 Configuration Backup and Restore ...... 137 Types of CLIs ...... 138 Sentences ...... 138 Wizards ...... 139 Menus ...... 139 Stateful ...... 140 Character vs. Line Interfaces ...... 140 Giving Users Access to a CLI ...... 140 The Laddie CLI ...... 141 Laddie Command Summary ...... 141 set logs on ...... 141 dump ...... 142 help ...... 143 Code Review for the test Command ...... 143 CLI Vocabulary: token.l ...... 144 CLI Grammar: syntax.y ...... 144 C Code ...... 145 Code Review Notes ...... 145 Summary ...... 145 x Contents in Detail 10 BUILDING A FRONT PANEL INTERFACE 147 Buttons, LEDs, and LCDs ...... 148 Buttons ...... 148 LEDs ...... 150 LCDs ...... 151 Designing a Front Panel UI ...... 152 Be Simple ...... 152 Try, Fail, Try Again ...... 153 Use LCD Menus and Modes ...... 154 Be Quick! ...... 155 The Laddie Front Panel ...... 157 Laddie LCD Menu System ...... 158 Laddie Front Panel Hardware ...... 159 Laddie Front Panel UI ...... 164 Improving Our Design ...... 166 Summary ...... 167
11 DESIGNING A FRAMEBUFFER INTERFACE 169 How Video Memory Works ...... 170 How Bytes in Video Memory are Interpreted ...... 170 How Video Memory Is Mapped to the Display ...... 172 The Linux Framebuffer Device Driver ...... 173 Manipulating the Framebuffer with open, read, write, and close ...... 174 Configuring the Framebuffer with the ioctl Command ...... 175 A Simple Graphics Program for the Framebuffer ...... 177 Graphics Libraries ...... 181 “Hello, world!” with SDL ...... 182 Initialize the Libraries ...... 183 Initialize the Framebuffer ...... 183 Create a Surface ...... 184 Display the Surface ...... 184 Handle Events ...... 185 Graphical UI Toolkits ...... 185 Building Simple UIs with STBmenu ...... 187 “Hello, world!” with STBmenu ...... 190 The Laddie Framebuffer UI ...... 193 Summary ...... 196
12 INFRARED REMOTE CONTROL 197 Communicating with Infrared Light ...... 198 Protocols for Encoding Remote Control Commands ...... 198 Reducing Interference by Modulating the Infrared Signal ...... 200 Controlling an Appliance with Infrared Light ...... 200 Hardware for Remote Control Receivers ...... 201 Detecting and Demodulating the IR Signal ...... 201
Contents in Detail xi Decoding Remote Control Waveforms ...... 203 Infrared Remote Control Hardware for the Laddie Appliance ...... 204 Installing and Configuring LIRC for the Laddie Appliance ...... 207 Installing the LIRC Software ...... 208 Configuring the lirc_serial Kernel Device Driver ...... 210 Testing the lirc_serial Driver ...... 212 Configuring the lircd Daemon ...... 215 Testing the lircd Daemon ...... 216 LIRC Tools for Controlling Applications ...... 218 Controlling the Laddie Appliance ...... 219 Summary ...... 220
13 HANDS-ON INTRODUCTION TO SNMP 223 A Quick Note on Terminology ...... 224 The Software ...... 225 Installing SNMP ...... 225 Download and Install ...... 226 Check the Installation ...... 226 Configure the Agent ...... 227 Start the Agent ...... 227 Exploring with SNMP ...... 228 MIB Files for Readable Names ...... 229 A Networked Printer ...... 231 The snmptable Command ...... 231 MIB-2: The TCP Connection Table ...... 232 MIB-2: The UDP Table ...... 233 MIB-2 Contents ...... 234 Writing Values with SNMP ...... 235 Setting sysContact ...... 235 Setting sysName ...... 237 SNMP Traps ...... 238 Receiving Traps with snmptrapd ...... 238 Traps That Carry Data: linkUp and linkDown ...... 240 Summary ...... 242
14 DESIGNING AN SNMP MIB 243 Our Goal ...... 244 Your Enterprise Number ...... 245 The MIB Files ...... 246 LADDIE-GROUP-SMI ...... 246 Creating the LAD-MIB ...... 249 Module Definition ...... 251 Version and Number of Zones ...... 253 The Alarm Table ...... 255 The Traps ...... 257 Validating Your MIB ...... 259 Summary ...... 260
xii Contents in Detail 15 IMPLEMENTING YOUR SNMP MIB 261 The Net-SNMP Agent ...... 262 The MIB Skeleton: mib2c ...... 265 The Header File: ladProject.h ...... 267 The Code File: ladProject.c ...... 267 Includes ...... 268 The Base OID ...... 268 MIB Objects Definitions ...... 268 RTA Access Routines ...... 271 The Initialization Routine ...... 274 The Scalars ...... 275 Reading the Alarm Table ...... 277 Writing the Alarm Table ...... 280 Makefile Revisited ...... 283 Debugging ...... 285 Traps ...... 285 Summary ...... 286
A RTA REFERENCE 289 Overview of RTA ...... 290 RTA Constants ...... 291 Data Structures ...... 292 API Subroutines ...... 296 The dbcommand() Subroutine ...... 297 The rta_add_table() Subroutine ...... 297 The SQL_string() Subroutine ...... 298 The rta_config_dir() Subroutine ...... 299 The rta_save() Subroutine ...... 299 The rta_load() Subroutine ...... 300 SELECT and UPDATE Syntax ...... 301 The SELECT Command ...... 301 The UPDATE Command ...... 302 Internal RTA Tables ...... 303 The rta_tables Table ...... 303 The rta_columns Table ...... 304 Debug Configuration ...... 304 Error Messages ...... 305 SQL Request Errors ...... 305 Internal Debug Messages ...... 306 Callback Routines ...... 307 Read Callbacks ...... 307 Write Callbacks ...... 308
B REVIEW OF SNMP 309 Why SNMP? ...... 310 Agents and Managers ...... 310 Namespace, Grammar, and Protocol ...... 310 The MIB ...... 311 The OID ...... 311 MIB-2 ...... 313
Contents in Detail xiii The SMI ...... 314 The SNMP Protocol ...... 316 The Basic Commands: GET, SET, GETNEXT ...... 316 Walking a MIB with GETNEXT ...... 316 Traps and Informs ...... 316 Command-Line Tools: Examples ...... 316 SNMPv1, SNMPv2, and SNMPv3 ...... 318 SNMP Data Types ...... 319 SNMP Tables ...... 320 Defining New Types ...... 321 Structure of a MIB File ...... 322 Summary ...... 324
C INSTALLING A FRAMEBUFFER DEVICE DRIVER 325 Finding Framebuffer Device Drivers for Your Video Card ...... 326 The vesafb Driver ...... 326 Hardware-Specific Drivers ...... 327 Drivers Not Included on the Laddie CD ...... 327 Configuring the Framebuffer Device Driver ...... 328 The vesafb Driver ...... 328 Hardware-Specific Drivers ...... 329
D A DB-TO-FILE UTILITY 331 Overview ...... 332 Table Definitions ...... 332 The tbl2file Table ...... 333 The tbl2field Table ...... 334 A tbl2filed Example ...... 335 Security Notes ...... 336
E THE LADDIE APPLIANCE BOOTABLE CD 337 Running the Laddie Appliance ...... 337 Booting the CD ...... 338 Navigating the Framebuffer User Interface ...... 338 Accessing the Web Interface ...... 339 Experimenting with the Linux Shell and Other User Interfaces ...... 339 Shutting Down the Laddie Appliance ...... 340 Exploring the CD Contents ...... 340 Laddie Appliance Source Code ...... 340 Laddie Appliance Libraries ...... 341 Startup Scripts ...... 341 The Linux From-Scratch Distribution and Additional Packages ...... 342 Rebuilding the Laddie Appliance ...... 342
INDEX 345 xiv Contents in Detail ACKNOWLEDGMENTS
As authors of the book we would like to thank Peter Enemark, Chris Sommers, and Keith Garrett for their unconditional support of this project and for their contributions to the technology presented. As readers of the book, you should thank our technical editor, Bob Lynch, for finding many, many errors in the text and on the CD. You should also thank Elizabeth Campbell, Riley Hoffman, and Megan Dunchak for changing some of our technically correct but completely incomprehensible sentences into something both readable and correct. Our thanks also go to Jon Colton, the artist responsible for the Tux’s Workshop series.
INTRODUCTION
Toasters, ovens, and dishwashers are a few of the appliances found in our everyday lives. Though we are quite familiar with their use, few of us stop to think about how an appliance works under the hood, or even what makes an appli- ance, well, an appliance. This book defines an appliance as a device designed to primarily perform a single function. If you think about the appliances just mentioned, you’ll see that this definition holds true— toasters toast, ovens bake, and dishwashers wash dishes. Compared to a PC, which is capable of performing thousands of diverse functions depending on the hardware and software installed, traditional appliances are boring and simple. What does this have to do with Linux? For starters, traditional appliances are no longer so simple. What used to be electrified but still mechanical devices, such as a vacuum cleaners, are now not only electronic, but include processors, circuit boards, and sophisticated user interfaces. With these changes comes the need to run an operating system on the appliance to manage the new features. Linux is a natural fit for this because it is low cost (in most cases, it is free to use) and open source (which means you can modify it to better suit your needs). However, the real place where Linux fits in is with the new types of appliances that are being designed. Digital video recorders (DVRs) were unheard of just a few years ago, but the first and most popular DVR appliance, the TiVo, runs on Linux, as do many other home networking and entertainment appliances. If you were to build the next great robotic house-cleaning system, you’d want to avoid designing it completely from scratch. You’d reuse as many parts as possible from your earlier robots, and you’d use off-the-shelf components wherever possible. The same reuse mentality applies to Linux appliances, and that’s where this book can help.
What This Book Is About This book shows you how to build a Linux appliance, and it includes a prototype appliance that you can use as the basis for your appliance, if you wish. We divide an appliance into daemons and user interfaces and show how to create and manage daemons, as well as how to build five different types of user interfaces. We cover the following topics: