THE APACHE MODULES BOOK
CHAPTER APPLICATIONS DEVELOPMENT WITH APACHE 1 1 A BRIEF HISTORY OF THE APACHE WEB SERVER 1 1 1 APACHE 1 1 1 2 APACHE 2 1 2 THE APACHE SOFTWARE FOUNDATION 1 2 1 MERITOCRACY 1 2 2 ROLES 1 2 3 PHILOSOPHY 1 3 THE APACHE DEVELOPMENT PROCESS 1 3 1 THE APACHE CODEBASE 1 3 2 DEVELOPMENT FORUMS 1 3 3 DEVELOPERS 1 3 4 PARTICIPATION 1 4 APACHE AND INTELLECTUAL PROPERTY 1 4 1 THE APACHE LICENSE 1 4 2 THIRD-PARTY INTELLECTUAL PROPERTY 1 5 FURTHER READING 1 5 1 INTERACTIVE ONLINE FORUMS 1 5 2 CONFERENCES 1 5 3 WEBSITES 1 6 SUMMARY CONTENTS CHAPTER THE APACHE PLATFORM AND ARCHITECTURE 2 1 OVERVIEW 2 2 TWO-PHASE OPERATION 2 2 1 START-UP PHASE 2 2 2 OPERATIONAL PHASE 2 2 3 SHUTDOWN 2 3 MULTI-PROCESSING MODULES 2 3 1 WHY MPMS? 2 3 2 THE UNIX-FAMILY MPMS 2 3 3 WORKING WITH MPMS AND OPERATING SYSTEMS 2 4 BASIC CONCEPTS AND STRUCTURES 2 4 1 REQUEST_REC 2 4 2 SERVER_REC 2 4 3 CONN_REC 2 4 4 PROCESS_REC 2 5 OTHER KEY API COMPONENTS 2 6 APACHE CONFIGURATION BASICS 2 7 REQUEST PROCESSING IN APACHE 2 7 1 CONTENT GENERATION 2 7 2 REQUEST PROCESSING PHASES 2 7 3 PROCESSING HOOKS 2 7 4 THE DATA AXIS AND FILTERS 2 7 5 ORDER OF PROCESSING 2 7 6 PROCESSING HOOKS 2 8 SUMMARY THE APACHE PORTABLE RUNTIME 3 1 APR 3 2 APR-UTIL 3 3 BASIC CONVENTIONS 3 3 1 REFERENCE MANUAL: API DOCUMENTATION AND DOXYGEN 3 3 2 NAMESPACING 3 3 3 DECLARATION MACROS 3 3 4 APR_STATUS_T AND RETURN VALUES 3 3 5 CONDITIONAL COMPILATION 3 4 RESOURCE MANAGEMENT: APR POOLS 3 4 1 THE PROBLEM OF RESOURCE MANAGEMENT 3 4 2 APR POOLS 3 4 3 RESOURCE LIFETIME 3 4 4 LIMITATIONS OF POOLS 3 5 SELECTED APR TOPICS 3 5 1 STRINGS AND FORMATS 3 5 2 INTERNATIONALIZATION 3 5 3 TIME AND DATE 3 5 4 DATA STRUCTS 3 5 5 BUCKETS AND BRIGADES 3 5 6 FILESYSTEM 3 5 7 NETWORK 3 5 8 ENCODING AND CRYPTOGRAPHY 3 5 9 URI HANDLING 3 5 10 PROCESSES AND THREADS 3 5 11 RESOURCE POOLING 3 5 12 API EXTENSIONS 3 6 DATABASES IN APR/APACHE 3 6 1 DBMS AND APR_DBM 3 6 2 SQL DATABASES AND APR_DBD 3 7 SUMMARY PROGRAMMING TECHNIQUES AND CAVEATS 4 1 APACHE CODING CONVENTIONS 4 1 1 LINES 4 1 2 FUNCTIONS 4 1 3 BLOCKS 4 1 4 FLOW CONTROL 4 1 5 DECLARATIONS 4 1 6 COMMENTS 4 2 MANAGING MODULE DATA 4 2 1 CONFIGURATION VECTORS 4 2 2 LIFETIME SCOPES 4 3 COMMUNICATING BETWEEN MODULES 4 4 THREAD-SAFE PROGRAMMING ISSUES 4 5 MANAGING PERSISTENT DATA 4 5 1 THREAD SAFETY 4 5 2 MEMORY/RESOURCE MANAGEMENT 4 6 CROSS-PLATFORM PROGRAMMING ISSUES 4 6 1 EXAMPLE: CREATING A TEMPORARY FILE 4 7 CROSS-MPM PROGRAMMING ISSUES 4 7 1 PROCESS AND GLOBAL LOCKS 4 7 2 SHARED MEMORY 4 8 SECURE PROGRAMMING ISSUES 4 8 1 THE PRECAUTIONARY PRINCIPLE: TRUST NOTHING 4 8 2 DENIAL OF SERVICE: LIMIT THE DAMAGE 4 8 3 HELP THE OPERATING SYSTEM TO HELP YOU 4 9 EXTERNAL DEPENDENCIES AND LIBRARIES 4 9 1 THIRD-PART LIBRARIES 4 9 2 LIBRARY GOOD PRACTICE 4 9 3 BUILDING MODULES WITH LIBRARIES 4 10 MODULES WRITTEN AND COMPILED IN OTHER LANGUAGES 4 11 SUMMARY WRITING A CONTENT GENERATOR 5 1 THE HELLOWORLD MODULE 5 1 1 THE MODULE SKELETON 5 1 2 RETURN VALUES 5 1 3 THE HANDLER FIELD 5 1 4 THE COMPLETE MODULE 5 1 5 USING THE REQUEST_REC OBJECT 5 2 THE REQUEST, THE RESPONSE, AND THE ENVIRONMENT 5 2 1 MODULE I/O 5 2 2 READING FORM DATA 5 3 THE DEFAULT HANDLER 5 4 SUMMARY REQUEST PROCESSING CYCLE AND METADATA HANDLERS 6 1 HTTP 6 1 1 THE HTTP PROTOCOL 6 1 2 ANATOMY OF AN HTTP REQUEST 6 2 REQUEST PROCESSING IN APACHE 6 2 1 MAPPING TO THE FILESYSTEM 6 2 2 CONTENT NEGOTIATION 6 2 3 SECURITY 6 2 4 CACHING 6 2 5 PRIVATE METADATA 6 2 6 LOGGING 6 3 DIVERTING A REQUEST: THE INTERNAL REDIRECT 6 3 1 ERROR DOCUMENTS 6 3 2 DEALING WITH MALFORMED AND MALICIOUS REQUESTS 6 4 GATHERING INFORMATION: SUBREQUESTS 6 4 1 EXAMPLE 6 5 DEVELOPING A MODULE 6 5 1 SELECTING DIFFERENT VARIANTS OF A DOCUMENT 6 5 2 ERROR HANDLING AND REUSABILITY 6 6 SUMMARY AAA: ACCESS, AUTHENTICATION, AND AUTHORIZATION 7 1 SECURITY 7 1 1 AUTHENTICATION: LEVELS OF SECURITY 7 1 2 LOGIN ON THE WEB 7 2 AN OVERVIEW OF AAA 7 3 AAA IN APACHE 1 X AND 2 0 7 4 AAA IN APACHE 2 1/2 2 7 4 1 HOST-BASED ACCESS CONTROL 7 4 2 AUTHENTICATION: CHECK_USER_ID 7 4 3 PASSWORD LOOKUP 7 4 4 AUTHORIZATION 7 5 AAA LOGIC 7 5 1 AUTHENTICATION AND REQUIRE 7 5 2 DENYING ACCESS 7 5 3 AUTHENTICATION METHODS 7 6 WRITING AAA MODULES 7 6 1 A BASIC AUTHENTICATION PROVIDER 7 6 2 AN AUTHORIZATION FUNCTION 7 6 3 CONFIGURATION 7 6 4 BASIC AND DIGEST AUTHENTICATION PROVIDERS 7 7 IMPLEMENTING A CUSTOM LOGIN SCHEME 7 7 1 SESSION MANAGEMENT WITH SQL 7 7 2 WORKING WITHOUT BROWSER AUTHENTICATION DIALOGS 7 8 SUMMARY FILTER MODULES 8 1 INPUT AND OUTPUT FILTERS 8 2 CONTENT, PROTOCOL, AND CONNECTION FILTERS 8 3 ANATOMY OF A FILTER 8 3 1 CALLBACK FUNCTION 8 3 2 PIPELINING 8 4 THE FILTER API AND OBJECTS 8 4 1 OUTPUT FILTERS 8 4 2 INPUT FILTERS 8 5 FILTER OBJECTS 8 6 FILTER I/O 8 7 SMART FILTERING IN APACHE 2 2 8 7 1 PREPROCESSING AND POSTPROCESSING 8 7 2 MOD_FILTER 8 7 3 FILTER SELF-CONFIGURATION 8 7 4 PROTOCOL HANDLING 8 8 EXAMPLE: FILTERING TEXT BY DIRECT MANIPULATION OF BUCKETS 8 8 1 BUCKET FUNCTIONS 8 8 2 THE FILTER 8 9 COMPLEX PARSING 8 10 FILTERING THROUGH AN EXISTING PARSER 8 11 STDIO-LIKE FILTER I/O 8 12 INPUT FILTERS AND THE PULL API 8 12 1 MODE 8 12 2 BLOCK 8 12 3 READBYTES 8 12 4 INPUT FILTER EXAMPLE 8 13 SUMMARY CONFIGURATION FOR MODULES 9 1 CONFIGURATION BASICS 9 2 CONFIGURATION DATA STRUCTS 9 3 MANAGING A MODULE CONFIGURATION 9 3 1 MODULE CONFIGURATION 9 3 2 SERVER AND DIRECTORY CONFIGURATION 9 4 IMPLEMENTING CONFIGURATION DIRECTIVES 9 4 1 CONFIGURATION FUNCTIONS 9 4 2 EXAMPLE 9 4 3 USER DATA IN CONFIGURATION FUNCTIONS 9 4 4 PREPACKAGED CONFIGURATION FUNCTIONS 9 4 5 SCOPE OF CONFIGURATION 9 4 6 CONFIGURATION FUNCTION TYPES 9 5 THE CONFIGURATION HIERARCHY 9 6 CONTEXT IN CONFIGURATION FUNCTIONS 9 6 1 CONTEXT CHECKING 9 6 2 METHOD AND <LIMIT> 9 7 CUSTOM CONFIGURATION CONTAINERS 9 8 ALTERNATIVE CONFIGURATION METHODS 9 9 SUMMARY EXTENDING THE API 10 1 IMPLEMENTING NEW FUNCTIONS IN APACHE 10 1 1 EXPORTING FUNCTIONS 10 1 2 OPTIONAL FUNCTIONS 10 2 HOOKS AND OPTIONAL HOOKS 10 2 1 A CLOSER LOOK AT HOOKS 10 2 2 ORDER OF EXECUTION 10 2 3 OPTIONAL HOOKS EXAMPLE: MOD_AUTHZ_DBD 10 3 THE PROVIDER API 10 3 1 IMPLEMENTATION 10 3 2 IMPLEMENTING A PROVIDER 10 4 PROVIDING A SERVICE 10 4 1 EXAMPLE: MOD_DBD 10 4 2 IMPLEMENTING THE RESLIST 10 5 CROSS-PLATFORM API BUILDS 10 5 1 USING PREPROCESSOR DIRECTIVES 10 5 2 DECLARING THE MODULE API 10 6 SUMMARY THE APACHE DATABASE FRAMEWORK 11 1 THE NEED FOR A NEW FRAMEWORK 11 1 1 APACHE 1 X/2 0 VERSUS APACHE 2 2 11 1 2 CONNECTION POOLING 11 2 THE DBD ARCHITECTURE 11 3 THE APR_DBD API 11 3 1 DATABASE OPERATIONS 11 3 2 API FUNCTIONS 11 4 THE AP_DBD API 11 5 AN EXAMPLE APPLICATION MODULE: MOD_AUTHN_DBD 11 6 DEVELOPING A NEW DBD DRIVER 11 6 1 THE APR_DBD_INTERNAL H HEADER FILE 11 6 2 EXPORTING A DRIVER 11 6 3 THE DRIVER FUNCTIONS 11 7 SUMMARY MODULE DEBUGGING 12 1 LOGGING FOR DEBUGGING 12 1 1 THE ERROR LOG 12 1 2 DEBUGGING 12 2 RUNNING APACHE UNDER A DEBUGGER 12 2 1 SERVER START-UP AND DEBUGGING 12 2 2 DEBUGGING AND MPMS 12 2 3 TRACING A CRASH 12 2 4 DEBUGGING A CORE DUMP 12 3 SPECIAL-PURPOSE HOOKS AND MODULES 12 3 1 STANDARD MODULES 12 3 2 FATAL EXCEPTION MODULES 12 3 3 MODULES TO DEAL WITH ABNORMAL RUNNING 12 4 FILTER DEBUGGING 12 4 1 MOD_DIAGNOSTICS 12 5 SUMMARY