Programming WebRTC Build Real Time Streaming Applications for the Web 1st Edition Karl Stolley
- 1. Programming WebRTC Build Real Time Streaming Applications for the Web 1st Edition Karl Stolley download https://ebookname.com/product/programming-webrtc-build-real-time- streaming-applications-for-the-web-1st-edition-karl-stolley/ Get Instant Ebook Downloads – Browse at https://ebookname.com
- 2. Instant digital products (PDF, ePub, MOBI) available Download now and explore formats that suit you... Real Time Communication with WebRTC Peer to Peer in the Browser 1st Edition Salvatore Loreto https://ebookname.com/product/real-time-communication-with- webrtc-peer-to-peer-in-the-browser-1st-edition-salvatore-loreto/ Real Time Java Platform Programming 1st Edition Peter C. Dibble https://ebookname.com/product/real-time-java-platform- programming-1st-edition-peter-c-dibble/ Linux for embedded and real time applications 2nd Edition Doug Abbott https://ebookname.com/product/linux-for-embedded-and-real-time- applications-2nd-edition-doug-abbott/ The Geopolitics of South Asia 3rd Edition Graham P. Chapman https://ebookname.com/product/the-geopolitics-of-south-asia-3rd- edition-graham-p-chapman/
- 3. Rendering in SketchUp From Modeling to Presentation for Architecture Landscape Architecture and Interior Design 1st Edition Daniel Tal https://ebookname.com/product/rendering-in-sketchup-from- modeling-to-presentation-for-architecture-landscape-architecture- and-interior-design-1st-edition-daniel-tal/ Hacking MythTV 11th edition Edition Jarod Wilson https://ebookname.com/product/hacking-mythtv-11th-edition- edition-jarod-wilson/ Solar Engineering of Thermal Processes 3rd Edition John A. Duffie https://ebookname.com/product/solar-engineering-of-thermal- processes-3rd-edition-john-a-duffie/ Captain James Cook Great Explorers 1st Edition William W. Lace https://ebookname.com/product/captain-james-cook-great- explorers-1st-edition-william-w-lace/ Memory fragments of a modern history First Edition Winter https://ebookname.com/product/memory-fragments-of-a-modern- history-first-edition-winter/
- 4. Strategies and Tactics in Organic Synthesis 7 1st Edition Michael Harmata (Eds.) https://ebookname.com/product/strategies-and-tactics-in-organic- synthesis-7-1st-edition-michael-harmata-eds/
- 7. Early praise for Programming WebRTC Programming WebRTC is an exceptional book that teaches WebRTC theory through practical application of the specification. Through an iterative approach to imple- menting a WebRTC application, Programming WebRTC somehow makes an ex- tremely difficult and nuanced topic approachable and easy to understand. It is a must-read book on the topic. ➤ Stephen Watzman Software Engineer Karl has a passion for WebRTC that shows in this book, and combining that with his experience as an educator and a technologist, he’s crafted a book that is very accessible and informative. WebRTC development has a lot of nuances, but Karl approaches the topic in a way that is both reader-friendly and technically comprehensive. I highly recommend it to anyone new to WebRTC! ➤ Arin Sime CEO/Founder, WebRTC.ventures Dr. Karl Stolley, a developer, technical author, and prominent WebRTC expert, has consistently addressed the field’s challenges and advancements in conferences, including the IIT RTC, and other academic settings. His insights highlight the dynamic nature of WebRTC implementations, yet underscore their current robust- ness through practical examples often employed in his teaching. ➤ Alberto Gonzalez Trastoy Software Consultant and CTO, WebRTC.ventures
- 8. This book expertly blends technical depth with humor, making WebRTC accessible. Even complex topics like signaling channels are tackled with wit, reminding us that a well-designed interface beats the “Imagine this doesn’t look like garbage” approach any day. ➤ Paul Freiberger co-author, Fire in the Valley
- 9. Programming WebRTC Build Real-Time Streaming Applications for the Web Karl Stolley The Pragmatic Bookshelf Dallas, Texas
- 10. For our complete catalog of hands-on, practical, and Pragmatic content for software developers, please visit https://pragprog.com. Contact support@pragprog.com for sales, volume licensing, and support. For international rights, please contact rights@pragprog.com. The team that produced this book includes: Dave Thomas Publisher: Janet Furlow COO: Susannah Davidson Executive Editor: Michael Swaine Development Editor: Vanya Wryter Copy Editor: Potomac Indexing, LLC Indexing: Gilson Graphics Layout: Copyright © 2024 The Pragmatic Programmers, LLC. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form, or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior consent of the publisher. When we are aware that a term used in this book is claimed as a trademark, the designation is printed with an initial capital letter or in all capitals. ThePragmaticStarterKit,ThePragmaticProgrammer,PragmaticProgramming,PragmaticBookshelf, PragProg and the linking g device are trademarks of The Pragmatic Programmers, LLC. Every precaution was taken in the preparation of this book. However, the publisher assumes no responsibility for errors or omissions, or for damages that may result from the use of information (including program listings) contained herein. ISBN-13: 978-1-68050-903-8 Encoded using recycled binary digits. Book version: P1.0—July 2024
- 11. Contents Acknowledgments . . . . . . . . . . . ix Preface . . . . . . . . . . . . . . xi 1. Preparing a WebRTC Development Environment . . . . 1 Installing Node.js 2 Downloading the Supporting Code and Installing Dependencies 2 Serving HTTPS in Development 4 Choosing a Development Browser 6 Starting and Stopping the Server 7 2. Working with a Signaling Channel . . . . . . . 11 Preparing a Basic Peer-to-Peer Interface 11 Adding Video Elements: Self and Peer 14 Styling the Core App Elements 17 Adding Functionality to the Call Button in JavaScript 22 Positioning WebRTC as a Front-End Technology 25 Using a Lightweight Signaling Channel 27 Connecting to the Signaling Channel 32 3. Establishing a Peer-to-Peer Connection . . . . . . 37 Requesting User-Media Permissions 37 Setting Up the Peer Connection 42 Building Connection Logic to the “Perfect Negotiation” Pattern 51 Receiving Media Tracks 59 Testing Out Your First Peer-to-Peer App 60 4. Handling Data Channels . . . . . . . . . . 63 Adding Basic Visual Effects to User Videos 64 Determining Peer-Connection States 68 Applying Filters Remotely with Data Channels 71
- 12. Uniquely Identifying Data Channels 73 Adding a Text-Chat Feature 75 Adding Logic to Handle Chat Events 81 Setting Up the Text-Chat Data Channel 83 Building a Message Queue 86 5. Streaming Complex Data . . . . . . . . . . 93 Structuring Chat Messages in JSON 93 Adding Mic and Camera Toggles 98 Refining the Initial Properties on Self and Peer 99 Building A/V Toggles 105 Sharing Features over Data Channels 112 Sending Images over the Chat 117 Sending and Receiving Binary Data 125 6. Managing Multipeer Connections . . . . . . . 133 Learning from a Failed Peer-to-Peer Call 134 Working with a Multipeer-Ready Signaling Channel 136 Revising the Signaling Logic on the Client 139 Generating Video Structures on the Fly 145 Initializing Peers as Needed 150 Fleshing out the Skeletal Signaling Callbacks 152 Working with Peer IDs in the handleScSignal() Callback 156 Restructuring WebRTC Callbacks with Closures 159 Sharing Features over Multipeer Data Channels 165 7. Managing User Media . . . . . . . . . . 173 Determining Device Availability 174 Detecting Device Changes 182 Removing User Media for Remote Peers 187 Programmatically Recognizing Denied Media Permissions 190 Setting and Applying Media Constraints Objects 193 8. Deploying WebRTC Apps to Production . . . . . . 197 Configuring a WebRTC App for Public Deployment 198 Configuring a Server to Host Your WebRTC App 202 Deploying Your App with Git 207 Monitoring Your App with PM2 210 Configuring Nginx for Reverse Proxies 212 Setting Up Your Own STUN/TURN Server 214 Contents • vi
- 13. A1. Connection Negotiation in Legacy Browsers . . . . 225 Implementing Backward-Compatible Fixes 225 Bibliography . . . . . . . . . . . . 231 Index . . . . . . . . . . . . . . 233 Contents • vii
- 14. Acknowledgments I wrote this book over the span of two very different careers and three jobs, with a global pandemic thrown in for good measure. Screenshots found throughout the book document my various hair lengths and unkempt beard for posterity. Thank you to my past and current employers, supervisors, and coworkers who in ways big and small graciously accommodated and supported my work on this: Ray Trygstad, Nina Kuruvilla & Kwindla Kramer, and Alya Abbott & Tim Abbott. Thank you to the students in my WebRTC classes who read and worked through the earliest iterations of this book, providing useful feedback that shaped what this work would ultimately become: Hareem Akram, Jon Andoni Baranda, Yelitza Castro, Chia-Chi Chang, Julaam J. Diop, Michael P. Kaczowka, David Singer, Rida Tariq, and Naveed Zahid. Thank you to my professional colleagues and friends who offered encourage- ment, interest, and support for this project: Nancy DeJoy, Molly Holzschlag, Carrie Malone, Jayne Mast, Kate McLaughlin, Adria Neapolitan, Brian Okken, Arin Sime, Alberto Gonzalez Trastoy, and Brian Watts. Thank you to my technical reviewers: Martin Deen, Tsahi Levent-Levi, and Kimberlee Johnson. Additional thanks to Dasha Day Hisholer for also reviewing this work while it was struggling to become a proposal. Special thanks to Aman Agrawal for his careful review of the completed book. I am solely to blame for any errors and shortcomings that remain. Thank you to the team at or closely orbiting Pragmatic Programmers: Tammy Coron, Tim Mitra, Erica Sadun, and especially Margaret Eldridge who, among other things, shepherded this work in its proposal form to a head-spinningly quick acceptance. report erratum • discuss
- 15. A special thank you to my editor, Michael Swaine, for his encouragement, bone-dry wit, and saint-like patience in helping me see this book through to completion. Working with him was the best writing experience of my career. And the deepest thank you to my family: to my dog, Hank, for his countless hours of unflagging dog assistance and posing for screenshots in front of a laptop. And to Amy, my incredible wife of almost 20 years, for her patience, support, and boundless love: you are the very best one. Acknowledgments • x report erratum • discuss
- 16. Preface WebRTC—or Web Real-Time Communication—is a standardized API exposed in all modern web browsers. The World Wide Web Consortium accepted the WebRTC specification as a full recommendation after a long decade of devel- opment.1 Couple a complete, stable specification with browser support for WebRTC ranging from rock-solid to serviceable, and you find yourself in a perfect environment for developing and deploying real-time web applications in the browser. Like any Web API, WebRTC doesn’t enjoy a perfectly spec-aligned implemen- tation in any browser. But this book will start you on your journey to devel- oping real-time streaming applications, all according to the certainty of a stable specification. You’ll also learn to write elegant, backward-compatible code to get your WebRTC apps working across the widest possible range of recent and modern browsers. Desktop and mobile devices, too. Support for WebRTC is everywhere. Your WebRTC Journey You’ll start your journey by getting straight to work on building a basic WebRTC application to support peer-to-peer video calling. Chapter by chapter, you’ll refine that app and its core logic to then spin up additional WebRTC- powered apps that will have your users sharing all manner of data with one another, all in real time. This book treats WebRTC as a part of the Web Platform. No third-party libraries or heavy downloads are required for you to make your way through this book, or for your users to use the WebRTC apps you build: you’ll be writing and strengthening your knowledge of modern HTML, CSS, and Java- Script to get the most out of browser-native WebRTC APIs. 1. https://www.w3.org/TR/webrtc/ report erratum • discuss
- 17. From the outside, WebRTC is pretty daunting. Okay, really daunting. I’m proud of you just for peeking inside this book. But don’t put it down just because WebRTC will challenge you and twist your brain around in some profound ways. That’s both expected and totally okay. It means you’re on the path. We’ll walk it together. Things look better and more manageable from the inside. This book will get you on the path to where you want to go with WebRTC right away. You won’t find any throwaway code or opaque, puzzling examples here. We’re going to be developing real WebRTC applications together from the outset. And it will be from those real, functioning applications that we will tease out how WebRTC works. By the end of your journey, you will have all the foundational skills and knowledge you need to build your own wildly imaginative real-time applications. And because work on the WebRTC speci- fication continues, you will also learn how to stay on top of the latest changes and discussions. Who Should Read This Book? This book is aimed at intermediate and advanced web designers and developers looking to explore and implement real-time communication features in new or existing web applications. Whether you consider yourself a designer or a developer, WebRTC is one of those rare Web APIs where design and development converge head on: not just conceptually, but in the actual code you’ll be writing. WebRTC is a front- end technology that requires only the teeniest, tiniest server-side component, which I have provided for you in the codebase that accompanies this book. Almost all of your work will be run and rendered directly in the browser. You should have at least some knowledge of JavaScript, along with HTML and CSS. I’ll do my best to fill in any gaps that might arise for you and point out additional books and resources that you might find useful. You’ll find yourself working with other Web APIs in this book—not just WebRTC. Many of those will equip you with added knowledge to enhance your work on all kinds of web applications, whether or not they include a real-time component. What’s Covered (And What’s Not) This book covers WebRTC’s APIs as natively implemented in recent and modern web browsers. You’ll be working with those APIs directly in vanilla JavaScript to build your knowledge and command of WebRTC independent of any third-party libraries. The promise of WebRTC has always been to provide Preface • xii report erratum • discuss
- 18. real-time communication right in the browser without requiring users to download special plugins or add-ons. Your users’ browsers already have everything needed to power your real-time app. All you have to do is build it! But to build a stunningly accessible and usable real-time application requires more than just a strong JavaScript foundation. It is an all-too-common mistake to think of WebRTC as just another conduit for media streams and application data. Because of its real-time component, WebRTC knits together two or more remote interfaces where real, live users are interacting and cooperating with one another. Building a WebRTC app without thinking carefully about the user interface would be like building a bicycle without the seat and handlebars. Ouch, right? So don’t be surprised to spend some time—perhaps more than you’d expect—working with HTML and CSS, too. You will be doing WebRTC development within the friendly confines of your local network for most of the book, but a chapter at the end will walk you through the necessary requirements and steps for deploying your real-time applications to the web, and testing them out. So what’s not covered? In a phrase, this book does not cover issues of scale or millisecond-obsessed WebRTC optimization. While there are a growing number of server-, platform-, and system-based implementations of WebRTC, as well as numerous WebRTC-based communication platforms as a service (CPaaS), those are all beyond the scope of this book. That means you won’t find coverage here of scaling apps up to handle dozens or thousands of con- current users supported by server-side technologies like selective forwarding units (SFUs) or multi-conference units (MCUs). Although you will work with a small server that provides a signaling channel, that is the extent of the server-side content in this book. And while you’ll learn about some fundamentals of streaming-media CODECs and optimization, this book does not go deep on those topics. Nor does it encourage session description protocol (SDP) “munging” to coerce browsers to use a particular CODEC, or fiddling with RTCRtpTransceiver objects. Native browser code for those matters is better tuned and tested than app-based adjustments likely ever will be. However, the core principles of WebRTC that we’ll look at in depth—working with a signaling channel, establishing peer connections, adding and managing media streams and data channels—will have you well prepared to tackle WebRTC implementations and third-party services wherever you might encounter them. report erratum • discuss What’s Covered (And What’s Not) • xiii
- 19. How This Book Is Organized This book is organized in a set of sequential chapters. It’s meant to be read more or less front to back. If that feels overly prescriptive and stifling, or if you’ve just got a rebellious streak that you like to take out on tech books, try anyway to make it through at least the first four chapters before you jump around to the later ones whose topics most interest you. In Chapter 1, you’ll learn how to set up a development environment that will play nicely with WebRTC. You’ll also learn how to get the most out of the starter and example code that accompanies the book. With your development environment set up and tested out, Chapter 2 dives right into the only necessary server component of WebRTC apps: a signaling channel. As part of working with the signaling channel, you’ll start to build the basic interface of your first WebRTC app, which provides peer-to-peer video calls. Chapter 3 is where you’ll really hit your stride working directly with WebRTC’s APIs, all of which orbit around the RTCPeerConnection interface. By the end of this chapter, you’ll be streaming video between two connected peers which—to start—will be two browser windows on your desktop. Streaming real-time user video and audio is WebRTC’s most famous feature. But that’s not its only feature. Over the course of Chapter 4 and Chapter 5, you’ll go from streaming basic data to streaming more complex data— including JSON as well as images and other binary files. WebRTC provides a powerful and flexible low-level interface for streaming arbitrary application data between two peers, all in real time. You’ll learn to command that interface, and abstract away subtle differences found in browsers with incomplete WebRTC implementations. You’ll even bring what you learn full circle by safely implementing user audio to complete the silent streaming video you’ll work with at first. Buckle your seatbelt when you get to Chapter 6. Connecting two peers is one thing. But how about connecting three or more peers? Chapter 6 will have you establishing WebRTC calls using a mesh-network topography to enable multiple peers to join the same call simultaneously. You’ll also experi- ence the theoretical and practical upper limits on the number of peers who can join a call on a mesh network, depending on what your app does and the amount of bandwidth and processing power it consumes. In Chapter 7, you’ll work more in depth with the MediaDevices interface on the Media Capture and Streams API to do things like help users determine what Preface • xiv report erratum • discuss
- 20. mics and cameras they have available, and handle edge cases in your logic when either there are no devices available, or users deny permission to access them. You’ll learn to do some minor media-stream optimization, too, with the aid of the built-in, real-time statistics that WebRTC implementations provide in the browser. Closing out the body of the book, in Chapter 8, you’ll learn how to deploy WebRTC applications to production. You’ll find a concrete deployment example, but you’ll also learn how to adjust that example to suit your own needs and preferences. And finally, you will find an appendix at the end of the book that will show you the necessary fixes for making your WebRTC applications work with legacy browsers that don’t support the WebRTC APIs necessary for perfect negotiation. Online Resources You can download the source code for studying and working alongside the examples in the book from pragprog.com.2 If you spot an error or even just come across something that is blocking your path forward in the book, con- sider this my personal invitation to you to join and post to the book’s forum on DevTalk.3 If you would like to contact me directly, I am available on Mastodon at @stolley@hachyderm.io.4 I also blog about WebRTC and other web topics at https://stolley.dev/ All right. Enough with the formalities that we classy preface readers enjoy while thoughtfully adjusting our monocles from the comfort of a high-back leather chair. Let’s pop out the monocle, pull open a laptop, and get down to it: it’s time to set up a development environment that will be your trusty companion on your exciting, monocle-free journey with WebRTC. 2. https://pragprog.com/titles/ksrtc/ 3. https://devtalk.com/books/programming-webrtc/errata 4. https://hachyderm.io/@stolley report erratum • discuss Online Resources • xv
- 21. CHAPTER 1 PreparingaWebRTC DevelopmentEnvironment Exciting new technologies often require developers to level up the sophistica- tion of their development environments. WebRTC is no exception. Almost everything you’ll be doing with WebRTC happens in and between browsers. While you’ll be writing HTML, CSS, and JavaScript just as you would for any other web application, there are some important things to set up to smooth your way through the rest of the book and your work building real-time web applications. In this chapter, you’ll install Node.js if you haven’t already. You’ll also learn where to get yourself a copy of the code that accompanies this book, and you’ll take a brief tour of the code’s organization so you can find what you need, when you need it. You’ll then generate and make use of your own self- signed certificates for serving HTTPS in development. HTTPS is necessary to fully and reliably access many newfangled, highfalutin Web APIs—including WebRTC, even in development. You’ll choose a WebRTC-ready development browser (spoiler: Chrome or Firefox), fire up the server that’s packed in with the book’s code to serve your in-progress work or the completed examples, and heroically machete your way through the dire security warnings that your browser will throw at you over your self-signed certificates. It’ll be a little bit of work, but once you’ve set this all up for yourself, you shouldn’t have to think about any of it again. All of the setup here should work without much fuss or drama on Unix-like operating systems, including macOS. report erratum • discuss
- 22. Install Windows Subsystem for Linux If you’re developing on Windows, you’ll need to install and use Windows Subsystem for Linux.1 Installing Node.js The small server I’ve written to support your local WebRTC development relies on Node.js, a wildly popular JavaScript runtime that you might already be familiar with and have installed. Let’s figure out if you’ve got a copy of Node.js already, and install one if you don’t. If you’re not sure if you have Node.js, run which node on your command line. You’ll see output showing the path to your Node.js installation, if you have one (now might be a good time to update it, if you haven’t in a while). If you see no output or know for a fact you aren’t running Node.js yet, no problem: there are a few different ways to install it. You can find, download, and run a Node.js installer for your operating system of choice from nodejs.org.2 Alternatively, if your operating system has a package manager available, such Homebrew for MacOS3 or your native package manager for Linux, you can install Node.js that way. However you opt to install Node.js, it’s generally a good idea to be running the latest LTS version.4 As a sanity check, once you’ve installed Node.js, you can run which node and which npm on your command line, which should report the locations where Node.js and its own package manager, npm, were installed. That’s simply confirmation that you’ve successfully installed Node.js, and also that your command line knows where to find it. Downloading the Supporting Code and Installing Dependencies Once you’ve set up Node.js, you should download the code for this book from pragprog.com.5 Once you’ve downloaded and decompressed the ZIP file,6 move 1. https://learn.microsoft.com/en-us/windows/wsl/install 2. https://nodejs.org/en/download/ 3. https://brew.sh/ 4. https://nodejs.org/en/about/previous-releases 5. https://pragprog.com/titles/ksrtc/programming-webrtc/ 6. https://media.pragprog.com/titles/ksrtc/code/ksrtc-code.zip Chapter 1. Preparing a WebRTC Development Environment • 2 report erratum • discuss
- 23. the unzipped code/ directory somewhere you can conveniently access from the command line. You might also want to rename the directory to something more recognizable than code/. Having done that, use your command line to navigate to the directory you’ve set up. Once you’re there, you need to install the dependencies for the server that you’ll rely on as you work through the book. Run this command: $ npm install A bunch of output will fill the terminal screen, but installation should only take a few minutes at most. Probably less. If you see warnings about deprecated packages, you can try running npm audit fix or the more aggressive npm audit fix --force to try and resolve matters. But for doing WebRTC development, it’s okay to ignore such warnings altogether. Finding Your Way Around the Code Directory I’ve prepared the book’s accompanying code to include the examples that I’ve written and a separate starter directory for you to follow along in the book and experiment on your own. Here is a brief look at what you’ll find in the code directory and where: • The book’s completed examples are each in their own subdirectory under demos/. You’ll see references to those files throughout the book. • There is a www/ directory for you to work in as you make your journey through the book. If you get stuck, you can always compare your work against the files in the demos/ directory. Don’t forget to mutter and curse about me under your breath, which you’ll find therapeutic. As you work through the book, you’ll often find yourself in those two directo- ries. But the accompanying code includes some additional files and directories that you might be curious about: • The deploy/ directory contains a standalone WebRTC app that you’ll use in Chapter 8, Deploying WebRTC Apps to Production, on page 197. • The server.js file contains a basic web server using the ExpressJS frame- work. This file includes the basic signaling channels that are discussed later in the book. • The scripts/ directory contains a server startup script, start-server, which (surprise!) starts the server, but you can simply run npm start on your command line to fire up the server. report erratum • discuss Downloading the Supporting Code and Installing Dependencies • 3
- 24. • For further study and your future experiments, you will find starter scripts for establishing peer connections in the _starter/ directory. p2p.js contains the logic necessary to establish a connection between two peers, and multi.js is enhanced with logic to establish a connection among three or more peers. Serving HTTPS in Development In order to develop WebRTC applications, it’s necessary to configure your development environment to serve HTTPS. Browsers disallow access to a number of APIs, including those that grant access to your microphone and camera, unless you’re serving HTTPS—even in development. To serve HTTPS in development, you’ll need to create and use your own self- signed certificates. It doesn’t take too much work to generate self-signed cer- tificates, but you can still impress your friends that you managed to serve HTTPS over localhost. Although self-signed certificates are not suited for use on the open web, they are perfectly acceptable for testing within the familiar comfort of your local network. The browsers you test your work on will nevertheless protest mightily, and they’ll do their best to scare you away from using self-signed certificates. And when that doesn’t work, they’ll try to make you feel bad about yourself. But don’t worry, and don’t feel bad: we’ll diffuse their unwarranted scare-and-shame tactics at the end of this chapter. Generating Self-Signed Certificates You’ll need access to openssl to generate your own certificate and key files on your operating system. MacOS and virtually all Unix-like operating systems and Linux distributions ship with openssl. If you’re a Windows user, you might need to install openssl yourself. The OpenSSL wiki maintains a list of download- able binaries.7 If you run Git Bash on Windows,8 it already includes openssl.exe, which you can also use. Before you generate the certificate files, you’ll need to create an easy-to- remember place for them to live. I recommend creating a Certs directory in your home directory: $ mkdir ~/Certs 7. https://wiki.openssl.org/index.php/Binaries 8. https://gitforwindows.org/ Chapter 1. Preparing a WebRTC Development Environment • 4 report erratum • discuss
- 25. The book’s supporting code you downloaded includes a script you can run to generate your certificate files. You’ll need to change into the directory where you’re storing the book’s code in order to do this. The base command is npm run ssl-keys, and it needs two arguments: the path to the directory you created (keydir) and the number of days before your self-signed certificates expire (numdays). For example, to create self-signed certificate files in ~/Certs that won’t expire for about five years (1825 days), you’d run this command in the book’s code directory: $ npm run ssl-keys --keydir="$HOME/Certs" --numdays=1825 Whatever values you choose, use the $HOME variable instead of the tilde, ~, and ensure there are no spaces around your equals signs. If you’re the suspicious type, you can examine the ssl-keys script in the pack- age.json file before you run it. It’s based on a command suggested by Let’s Encrypt,9 which is ordinarily in the business of offering free certificates that can be used on world-facing websites. If you’d prefer, you can head over to Let’s Encrypt’s original post10 and copy from there into your command line instead of using the npm script. You’ll need to change into your certificates directory before running the Let’s Encrypt command to generate the certificate and key files. By default, openssl creates certificates that expire in one year. If you want to go longer than that without having to generate new ones, add -days followed by some number of days to the Let’s Encrypt script, like -days 1825 to create five-year certificates. However you generate your keys, once you hit Return, it will only take a moment to generate the key and certificate files in the directory you’ve chosen, like ~/Certs. Creating those files is an important first step to serving HTTPS. But you’ll also need to make sure that any scripts and servers you run can find your certificate files with as little fuss as possible. Let’s set that up next. Storing the Certificate File Locations in Environment Variables You’ll need to export two environment variables from your command line’s startup scripts. Those variables will point to the location of your self-signed certificate files. Your startup scripts will be in a file in your home directory called .bashrc or .bash_profile, if you’re a bash user, .zshrc if you’re a zsh user, or possibly even a file called .profile. 9. https://letsencrypt.org/ 10. https://letsencrypt.org/docs/certificates-for-localhost/ report erratum • discuss Serving HTTPS in Development • 5
- 26. Whichever startup file your command line uses, open it in your favorite text editor, and add the following lines: # SSL Keys export LOCALHOST_SSL_CERT="$HOME/Certs/localhost.crt" export LOCALHOST_SSL_KEY="$HOME/Certs/localhost.key" Be sure not to put any spaces around the equals signs, =. And don’t forget to adjust the path if you’ve saved your keys somewhere different from ~/Certs or named them something other than localhost.crt and localhost.key. Once you’ve saved your startup file, reload it in your terminal using the source command. You’ll need to reference the name of the file your command line uses. In this example, the file is called .zshrc: $ source ~/.zshrc As a quick sanity check, you can confirm that your command line knows about these variables by using echo to output their values. To do this, prefix the variable names with a dollar sign: $ echo $LOCALHOST_SSL_CERT If everything has gone according to plan, you’ll see the certificate location you specified output by your command-line shell for LOCALHOST_SSL_CERT. On MacOS, for example, that will look something like /Users/username/Certs/localhost.crt. You can check the LOCALHOST_SSL_KEY value the same way, if you’d like. Choosing a Development Browser You’ll have the best possible development experience running the latest version of either Chrome or Firefox. I personally prefer Firefox Developer Edition,11 but the choice is yours. Whichever browser you choose, you’ll need to open its developer console and disable caching, so you always load the latest version of your CSS and Java- Script as you work. Firefox and Chrome both have the Disable Cache option under the Network tab of the developer pane. If you’re like me, you’ll opt to pop the developer console into its own window to maximize your available screen space. You’ll be building responsive interfaces that take advantage of the entire viewport. And you know the kinds of divas interfaces can be: steal their spotlight in any way and they’ll make your life miserable and spread salacious rumors about you to their friends. 11. https://www.mozilla.org/en-US/firefox/developer/ Chapter 1. Preparing a WebRTC Development Environment • 6 report erratum • discuss
- 27. What About Safari? Safari has historically lagged in its WebRTC implementation, but as of April 2022’s release of Safari 15.4, it is also up to snuff. If you opt to use Safari as your develop- ment browser, or if you want to test out your work on an iPhone or iPad, please be sure you’re running at least Safari 15.4. Incomplete WebRTC implementations in older versions of Safari and other browsers (Firefox prior to version 80, and Chrome prior to version 75) will give you a series of raging headaches. Consult Appendix 1, Connection Negotiation in Legacy Browsers, on page 225 to learn about the fallbacks you’ll need to add to your code for the sake of older browsers, for as long as they remain in use (if history is a guide, that will be awhile). Starting and Stopping the Server I’ve tried to make it as painless as possible for you to serve both your own work and the completed demos over localhost. To serve your own files as you work on them, run npm run start or simply npm start on the command line. Your files are more important, so they get the more convenient commands. Remember to Install Dependencies If you haven’t yet run npm install, be sure to do so before starting the server, or if you encounter errors about missing modules. To serve the book’s completed examples, you’ll need to run the slightly more verbose command npm run start:demos. No space on either side of the colon. Whenever you start the server, you’ll see output like this in your terminal window: signaling-server: ** Serving from the www/ directory. ** signaling-server: signaling-server: App available in your browser at: signaling-server: signaling-server: -> https://127.0.0.1:3000/ signaling-server: -> https://192.168.1.6:3000/ signaling-server: signaling-server: Hold CTRL + C to stop the server. signaling-server: signaling-server: +0ms report erratum • discuss Starting and Stopping the Server • 7
- 28. Each time you start the server, it will tell you which directory you’re currently serving from (again: www/ with your work, demos/ with the completed examples) and at least two addresses for reaching the server from your development browser of choice. Whenever you need to stop the server, hold down CTRL + C. The first time you start the server, your operating system might notify you about a firewall restriction of some kind. Because you’ll eventually be hitting this server from other devices connected to your local network, instruct your OS to allow incoming connections. With the server still running, you can open your browser to https://localhost:3000/. Of course localhost is a shortcut for 127.0.0.1, which you can also use if you get a thrill out of typing numbers and dots: https://127.0.0.1:3000/. Don’t worry for now about the second IP address you see. It will almost certainly be different from 192.168.1.6, but eventually you will be able to use whatever that second address is to test your app using other devices connected to your local network. One big gotcha: you absolutely must type out the full https:// protocol portion of these URLs. If you leave the protocol off, your browser will try to establish a connection over http://. The server isn’t actually listening for HTTP, but HTTPS. Your browser doesn’t know that, though, so it’ll dismissively inform you that it’s unable to connect. And you’ll lose a whole part of the day tracking down that missing s, which is made even more difficult to spot in browsers that hide the http:// protocol string on HTTP URLs. Once you enter the exact HTTPS-serving address, you’ll immediately hit a snag. Your browser, which demanded that you type out https:// in the address bar, now wants you to know that it has a big problem with your self-signed certificates. Instead of seeing the page the server is serving, you’ll get a security warning. Getting Past Browser Security Warnings After you point your browser to any of the server’s local https:// URLs, the browser viewport will fill with dire warnings, bad omens, and tales of an ancient curse. Firefox Developer Edition, for example, will present the screen on page 9. On the open web, these security warnings are a good thing. But in develop- ment, they’re just overly dramatic, pearl-clutching pains in the neck. The good news is that you’ll likely see this warning only the first time you hit your local address, and you will have to take these steps only once, too. To Chapter 1. Preparing a WebRTC Development Environment • 8 report erratum • discuss
- 29. get Firefox to chillax and let you get on with your work, click the Advanced… button, and then the Accept the Risk and Continue button in the box that appears. On Chrome, you’ll likewise click Advanced and then the “Proceed to localhost (unsafe)” link. Safari makes you jump through a different series of hoops to accept self- signed certificates: when confronted by Safari’s warning screen, click on Show Details, then the “visit this website” hyperlink. That’s all you have to do on iOS, thankfully. But on MacOS, you’ll then be greeted by a popup asking, “Are you sure you want to visit this website on a connection that is not pri- vate?” Click “Visit Website” and then you’ll see another popup: “You are making changes to your Certificate Trust Settings.” Click Use Password… and then enter the password you use to log into your Mac. report erratum • discuss Starting and Stopping the Server • 9
- 30. Discovering Diverse Content Through Random Scribd Documents
- 31. CHAPTER XXXVIII. ADVANCE TO KORTI. Meanwhile disquieting rumours with regard to Gordon had reached Cairo, and Sir Evelyn Baring telegraphed to Lord Wolseley on November 3rd, asking him whether he had any reason to believe that there was any foundation for the reports which had been current in Cairo for the last few days, that Khartoum had been taken, and that Gordon was a prisoner. Lord Wolseley telegraphed from Dongola the same day to the following effect:— "Major Kitchener telegraphs to Sir C. Wilson that he has seen a man named Ibrahim Wad-Beel, who recently came from the Arabs some distance south. He said all was quiet, and when Gordon received our messenger, he fired a salute, and held a parade of troops. A second telegram from Major Kitchener, dated November 3, announces that Haji Abdallah had arrived, and stated that a man from Shendy reported that the Mahdi came with a strong force to Omdurman and asked General Gordon to surrender. General Gordon replied that he would hold Khartoum for years."
- 32. The information as to the position of Khartoum up to this date was as follows:— On the 8th October a letter had reached Cairo from M. Herbin, the French Consular Agent at Khartoum. It was as follows:— "Khartoum, July 29, 1884. "We are in a strong position at Khartoum. No need for alarm, unless it be the want of provisions (in two months our provisions will be exhausted). There is abundance of ammunition. The least assistance would enable us to relieve the town. If at the moment of eating our last biscuit we were to attempt to retire in a body northwards, the retreat could only be effected at the cost of immense exertions and dangers (the means of transport are wanting). Besides this, the people would rise to a man to pillage the convoy. A few determined men might attempt to escape southwards to the Equator, but it would be necessary to abandon most of our soldiers, and all the women and children. Gordon Pasha has decided that he will share the fate of the town, and I think it my duty to share that of the few Frenchmen shut up here. Except for unforeseen circumstances, you can even now foresee what will happen." On October 31st Sir E. Baring had received a telegram stating that an Arab of the Kababish tribe had brought the news that the Mahdi's troops had attacked Gordon's force at Omdurman opposite Khartoum, a few days before, but the attack was repulsed. In a telegram dated Debbeh, November 2nd, a correspondent gave the following additional news:—
- 33. "Gordon attacked the rebels at Omdurman with a flotilla of twelve vessels, including steamers. For eight hours the engagement lasted. There were 25,000 rebels, and they had four Krupp guns. One gun burst. They retreated, leaving enormous numbers of dead behind them. The fugitives retired to Markeat, but were returning with an additional force." On the 1st November, Sir E. Baring had received communications from Gordon to the effect that on the date they were sent off, viz., 13th July, Khartoum was "all right and could hold out for four months." The next letter received from Gordon appears to have been the following. Though dated in August, it was not received till the 23rd November. It was as follows:— "General Gordon to Sir E. Baring. "Khartoum, August 5, 1884. "We are sending up steamers to Senaar, on Blue Nile, to open route. Arabs have left our vicinity in nearly all directions. When steamers come back we hope to recapture Berber by surprise, to place garrison in it, and Stewart and Power will descend Nile to Dongola and communicate with you. The garrison of Berber (to which I shall give provisions for three months) will be the Egyptian troops from this place; and I also shall make the foreign Consuls go down to Berber. I can look after security of Berber for two months, after which time I cannot be longer responsible for it, and you must relieve it from Dongola, or let the garrison perish and Berber be again taken by Arabs. You will dislike this arrangement,
- 34. perhaps, but I have no option; and it would entail no risks to you, seeing that Berber will be held during your advance. "All well here, and troops elated at the result of their recent victories." Notwithstanding every effort to get the troops up the river as rapidly as possible, so many difficulties intervened that the task occupied much longer than had been anticipated. Early in November Wolseley telegraphed that, owing to steamers breaking down, difficult coaling, and scarcity of native labour, he did not expect to concentrate his force at Ambukol, on the Nile just above Old Dongola, until the end of the year. The necessity for pushing forward with all possible despatch was made clear to Wolseley by a letter of much later date, received from Gordon on the 17th November, saying that he could hold out for forty days with ease, but that after that time it would be difficult. The following is an extract:— "Khartoum, 4th November, 1884. "Post came in yesterday from Debbeh, Kitchener, dated 14th October, cypher letter from Lord Wolseley, 20th September last, which I cannot decipher, for Colonel Stewart took the cypher with him. No other communications have been received here since 31st, letter which arrived a week after Stewart's steamer left this. "At Metammeh, waiting your orders, are five steamers with nine guns. We can hold out forty days with ease; after that it will be difficult. Terrible about loss of steamer. I sent Stewart, Power, and Herbin down, telling them to give you all information. With
- 35. Stewart was the journal of all events from 1st March to the 10th September. The steamer carried a gun and had a good force on board. "Since 10th March we have had up to date, exclusive of Kitchener's 14th October, only two despatches; one, Dongola, with no date; one from Souakim, 5th May; one of same import, 27th April. I have sent out a crowd of messengers in all directions during eight months. I should take the road from Ambukol to Metammeh, where my steamers wait for you. Leontides, Greek Consul-General, Hanswell, Austrian Consul, all right. Stewart, Power, and Herbin went down in the Abbas. Your expedition is for relief of garrison, which I failed to accomplish. I decline to agree that it is for me personally. You may not know what has passed here. The Arabs camped outside Khartoum on the 12th March; we attacked them on the 16th March, got defeated and lost heavily, also a gun. We then from that date had continual skirmishes with Arabs. * * * * * "The soldiers are only half a-month in arrears. We issue paper money, and also all the cloth in magazines. All the captives with the Mahdi are well. The nuns, to avoid an Arab marriage, are ostensibly married to Greeks. Slatin is with Mahdi, and has all his property, and is well treated; but I hear to-day he is in chains. "A mysterious Frenchman105 is with Mahdi, who came from Dongola. We have got a decoration made and distributed, with a grenade in the centre; three classes—gold, silver, pewter. Kitchener says he has sent letters and got none in reply. I have sent out during last month at least ten. Steamer with this
- 36. leaves to-morrow for Metammeh. Do not let any Egyptian soldiers come up here; take command of steamers direct, and turn out Egyptian fellaheen. If capture of steamer with Stewart is corroborated, tell French Consul-General that Mahdi has the cypher he gave Herbin. Hassen Effendi, telegraph clerk, was with Stewart. You should send a party to the place to investigate affairs and take the steamer." On the 15th November, Lord Hartington telegraphed to Lord Wolseley to know how the information in Gordon's letter affected his plans. In reply, his Lordship, who had gone back to Wady Halfa, to hurry forward the expedition, stated that Gordon's letter made no change in his plans, but that it seemed to indicate the almost impossibility of Gordon's relief without fighting, adding that he, Wolseley, had sent Gordon the following message:—"Wady Halfa, November 17, 1884. Yours of 4th inst. received 17th; the first I have had from you. I shall be at Kasr Dongola in four days." A few days later an Arab merchant who arrived at Dongola from Khartoum viâ Shendy and Ambukol, and who had come by the desert route, stated that both water and fodder were plentiful. This news was confirmed by a messenger who returned to Dongola from Khartoum on the 19th November. On the 28th a messenger sent by Gordon arrived at Dongola with a letter addressed to the Khedive, Nubar Pasha, and Baring, in cypher, and dated as far back as the 9th September. The letter began:— "There is money and provisions in Khartoum for four months, after which we shall be embarrassed." A telegram from Gordon to Sir E. Baring and Nubar Pasha, undated, but received 29th November, gave the following details:—
- 37. "Seeing now that the Nile is high, and steamers can go as far as Berber, I have formed an expedition of 2,000 men of the Khartoum garrison, which will proceed by steamers in order to rescue the Mudirieh of Berber from the hands of the rebels. After its recovery this force will remain at Berber with food for two months only, and if in that time the relieving army does not reach Berber in order to reinforce it, the Nile will have fallen and the islands will be dry, and the same result will ensue as before. Therefore it is to be hoped that the necessary troops will be sent to seize the Ghesireh of Berber while the Nile is high; and Stewart is going down in the small steamer, the Abbas, to proceed to Dongola by way of Berber, in order to communicate (with you) on the Soudan question." On the 29th November a messenger who had been despatched with a letter to Gordon, but had been taken prisoner not far from Khartoum, and had subsequently made his escape, came into camp. He reported that the Mahdi's troops were suffering from disease, food was very dear, the Arabs were deserting, but the Kordofan men were faithful to him; that Gordon sent to the Mahdi, inviting him, if he were the real Mahdi, to dry up the Nile and cross over; that five hundred regulars recently went over to Gordon; that the regulars still with the Mahdi were discontented; that on the 14th he saw an attack made on Khartoum between the Blue and White Niles; that it was repulsed, and the Mahdi, who was looking on, was very angry because it had been made without his orders. Aware that time was of paramount importance, Wolseley, in order to stimulate his men to exertion, offered a prize of £100 to the battalion which should make the quickest passage from Sarras to Debbeh, twenty miles further up the river, a measure which was much criticized by a portion of the British Press.106
- 38. Wolseley now gave orders for the formation of a small naval brigade, to be commanded by Lord Charles Beresford, his naval aide-de-camp.107 On the 23rd November, some cases of smallpox having occurred at Dongola, Sir Herbert Stewart started to select another camping- ground at Debbeh, a little further up the river. All the remaining troops destined to take part in the expedition reached Wady Halfa by the end of November, with the exception of the 1st battalion of the Cameron Highlanders, which remained at Korosko. The advance in force from Dongola commenced on the 2nd December, from which date the troops as they arrived were moved on beyond Debbeh to Ambukol, where a depôt for supplies had been formed and placed in charge of Stewart. The head-quarters were established at the latter place on the 12th December. From Ambukol the force was moved a few miles further up the river to Korti, a much healthier spot. Sir Herbert Stewart, with the Mounted Infantry and Guards' Camel Corps, reached Korti on the 15th December, after a march along the east bank of the Nile. Wolseley's arrival at Korti on the 16th was followed by that of the South Staffordshire Regiment. The last companies of the South Staffordshire, with part of the Sussex Regiment, reached the front on the 22nd, and they were speedily followed by other detachments. The Light Camel Corps, under Colonel M'Calmont, arrived on the 24th, after a twenty days' march from Wady Halfa, and at the same time the Heavy Camel Corps came up from Debbeh. General Buller, the Chief of the Staff, reached the front soon afterwards. Of the Nile journey Wolseley reported to Lord Hartington, "The English boats have up to this point fulfilled all my expectations. The men are in excellent health, fit for any trial of strength, as the result of constant manual labour."
- 39. As a commentary on the above, it may be mentioned that nine out of sixteen boats which brought up some of the Duke of Cornwall's Regiment were lost, and the remainder, owing to the slightness of their build, had to be patched with tin to prevent their sinking—over fifty boats in all were lost. There can be no doubt as to the "constant manual labour" mentioned by Lord Wolseley. The men arrived in a deplorable plight, many of them without either boots or trousers. A more ragged set of soldiers never arrived at the seat of war. According to one account there was literally not a sound garment in the whole column, and the men resembled Falstaff's ragged regiment rather than a body of British troops. By Christmas Day, a great part of the expeditionary force was concentrated at Korti.108 It now became necessary to decide upon the route to be adopted by the expeditionary force in order to reach Khartoum. The one important question to consider was that of time; already the journey up the river had taken much longer than was expected. The season during which military operations could be carried on was limited, and if, as had been intended, the expedition was to return before the hot weather there was not a day to spare. Moreover, Gordon's latest communications showed that he was rapidly running short of provisions, and if not speedily relieved Khartoum must fall. As a military operation, the route by the Nile offered many advantages, and had time permitted there is no doubt that Wolseley's whole force would have gone that way. But the distance to be traversed requiring months for its accomplishment, rendered it imperative to adopt some other expedient if Gordon was to be relieved at all. Under these circumstances, it was determined to divide the expeditionary force into two columns, one to proceed across the desert to Metammeh, a distance of 185 miles, and thence to Khartoum, and the other to proceed by the river up the Nile Valley. Shortly stated, Wolseley's plans for the campaign were as follows:—
- 40. 1st. By despatching a column across the desert to Metammeh to secure the shortest passage to Khartoum, and at the same time to hold the wells at Gakdul and Abu Klea, and to occupy Metammeh whilst communications were maintained with Gordon. 2nd. By despatching a second column along the Nile Valley to disperse the rebels around Hamdab, fifty-two miles distant from Korti, to punish the Monassir tribes for the murder of Colonel Stewart, to leave Berti in safety, to rid Abu Hamid of the enemy, and to open up the desert route from thence to Korosko, whence stores and ammunition for an attack on Berber would be forwarded. Thus covering a great bend of the Nile, the column would operate on Berber, dislodge the rebels there, and join hands with the other column on the banks of the Nile at Metammeh. In a letter to the Secretary at War, Wolseley gives the reasons for adopting the above plan of operations in the following words:— "I had always thought it possible that upon arrival here I might find it necessary to operate beyond this point in two columns—one continuing up the river in our English-built boats, while the other pushed rapidly across the desert to Metammeh, and it was with the view of securing to myself the power of moving across this desert that I proposed the formation of a Camel Brigade. "Any march across this desert with a small column, as an isolated operation, would be hazardous, and for the purpose of my mission a most useless undertaking. Such a column would most probably be able to fight its way into Khartoum; possibly it might fight its way out again; but it could never bring away General Gordon and his garrison in safety. Undertaken, however, under present circumstances, the march of a small force across this desert presents a very different aspect. The so-called Mahdi and his supporters are well aware that
- 41. they have to deal not only with it, but also with the English army, which they know is advancing up the Nile on Khartoum by Abu Hamid and Berber. Upon arrival here I had to decide whether I should keep all my force together and follow the Nile Valley to Khartoum, or to divide it into two columns—one following the river, while the other was pushed rapidly across to Metammeh. "If I were not restricted by time, the first course would be by far the most satisfactory, the safest, and would insure the best results; but I know that General Gordon is pressed by want of food, and the hot season is not far off, when military operations in this country are trying to the health of European soldiers. I therefore decided upon the last-mentioned course." The first, or Desert column, was placed under the command of Sir Herbert Stewart, and consisted of men mainly belonging to different sections of the Camel Corps; a company of the Royal Engineers, part of the 19th Hussars, and detachments of the Commissariat and Medical Corps. The force was to be accompanied by 2,000 camels for the purposes of transport. Sir Charles Wilson was to proceed with Stewart, and to the former was allotted the task of opening up communication with Gordon when once the Nile should be struck at Metammeh. Lord Charles Beresford and a small body of seamen were told off to accompany the force, to take possession of any of Gordon's steamers which might be found at Metammeh. A detachment of infantry was to proceed to Khartoum by the steamers, and Sir Charles Wilson was empowered on entering Khartoum to march his men through the city to show the people that British troops were at hand, but he was directed only to stay long enough to confer with Gordon.
- 42. The Nile column was placed under Major-General Earle, and consisted of the Staffordshire and Duke of Cornwall's Regiments, the Black Watch, the Gordon Highlanders, a squadron of the 19th Hussars, a battery of Egyptian Artillery, an Egyptian Camel Corps, and the auxiliary native troops of the Mudir of Dongola. The whole, with transport, numbered about 3,000 men.
- 43. CHAPTER XXXIX. STEWART'S DESERT MARCH. The march across the desert being determined upon, the first step was to seize and hold the wells of Gakdul, some ninety-five miles distant, and there establish a depôt for ammunition, provisions, and stores. This being accomplished, and a garrison being left to guard the post, the remainder of the force, with the baggage animals, were to return to Korti and make a fresh start with further supplies. This somewhat cumbrous arrangement was necessitated by the insufficient transport at the General's disposal. On the 30th December, Stewart's force, consisting of 73 officers, 1,032 non-commissioned officers and men, 2,099 camels, and forty horses, paraded for inspection on the rising ground south of Korti, preparatory to the march across the Bayuda Desert. The baggage-camels were arranged in columns, with from twenty to thirty marching abreast, and with fifty yards interval between each troop. The Guards in front and the Mounted Infantry in the rear were in close companies ready to dismount and form square at a moment's notice. Wolseley inspected the whole, and in the afternoon the cavalry scouts, under Major (afterwards Sir Herbert) Kitchener with some Arab guides, moved off in front. A little later the great column got in motion, striking straight off across the undulating and pebbly plain towards the distant horizon. It was a strange sight to see the camels, with their necks stretching
- 44. out like ostriches and their long legs, moving off in military array, until the rising dust first blended desert, men, and camels in one uniform grey hue, and finally hid them from the sight of those who remained in camp. Scared gazelles rose from among the rocks and bounded away across the desert, from time to time, as the force advanced. Broad as was the face on which this column marched, it extended fully a mile in length. The first halt was made at five p.m. with a view to ascertaining the whereabouts of the Hussars, who had gone on in the morning to collect wood and light fires at the first halting-place. After some time it was discovered that they had taken the wrong route, and it was not till midnight that they joined the column. The halt lasted for an hour and a half. General Stewart then gave orders for the column to close up, and for the camels to proceed on a broader front.
- 45. When they moved on again in the bright moonlight, the length of the column was reduced to half-a-mile, and was not only under better control on the line of march, but more able to resist any sudden attack. The march continued until early in the forenoon of the 31st, when a long halt was called, and the camels were unloaded. There was some excitement among the men when they halted for the first bivouac, owing to the uncertainty as to the whereabouts and disposition of the inhabitants. Only a few huts were visible, and these were deserted. Plenty of green fodder was obtainable, and the troops remained on the spot undisturbed until three in the afternoon, when a fresh start was made.
- 46. The force now marched through a beautiful country. Great spreading plains covered with mimosa and scrub succeeded one another, bounded by black rocky mountains, through the gorges of which the troops passed only to emerge on fresh tracts of the same character. The formation observed almost throughout the march was columns of companies, and the force was so distributed that in two minutes three squares could be formed in échelon to resist any attack. At a quarter-past five the column again halted, and then, with a bright moon, resumed its way, passing the wells of Hambok, where only a small supply of water was found. After leaving Hambok the route was amidst verdant trees and long grass, forming quite a contrast to what one would expect in a so-called desert. Shortly after midnight a halt was made at the wells of El Howeiyah. At 8.30 on the 1st January, 1885, the march was resumed till one p.m., when a halt was made during the heat of the day. Thus far the column had met neither friends nor foes, but just before this halt the capture was made of a man and his family, who were watching their flocks. The man, who turned out to be a noted robber chief, was thenceforth made use of as a guide. Later in the afternoon the column marched again until dark, then, waiting until the moon rose, resumed its way. Without any further halt the column continued its march throughout the night. During the night one or two prisoners were taken; one of them being an Arab from Metammeh, who gave important information. At four a.m. on the 2nd the force was opposite the wells of Abou Halfa, three miles from the main track. A company of Mounted Infantry was sent to seize the wells. This was effected, only a few natives being seen, and these fled at the approach of the troops. Three hours later the mouth of the gorge leading to Gakdul wells, distant 95 miles from Korti, was reached. The column had occupied forty-six hours and fifty minutes on the march, and been
- 47. thirty-two and three-quarter hours actually on the move. There had been no casualties on the road, and the men, although they had remained almost without sleep since leaving Korti, were in the best of spirits. The wells at Gakdul proved to be three in number, situated at the north end of a large circular plain or natural amphitheatre, surrounded by steep rocks of yellow sandstone some 300 feet in height. The day was occupied in watering the camels. At eight p.m. Sir Herbert Stewart, with all the camels and the whole force except the Guards and Engineers, started on the return journey to Korti. The force, numbering in all about 400, which was left to guard the wells, set to work under Major Dorward, of the Royal Engineers, to construct three forts on the high ground, and made improvements in the arrangements for watering and in the means of access to the wells. Major Kitchener's Mounted Infantry captured a convoy of camels laden with dates for the Mahdi. The appearance of natives in the neighbourhood was reported, but otherwise the little party at the wells met with no excitement. On the 11th a convoy of stores and ammunition, under Colonel Clarke, arrived at the wells from Korti. Stewart and the column which accompanied him back from Gakdul returned to Korti on January the 5th. Lord Wolseley rode out to meet the column and complimented the General on his achievement. The prisoners taken stated that Metammeh was occupied in force by the Mahdi's army. Some put the fighting men there at 2,000, others said that there were 5,000. The enemy had thrown up an intrenchment and were prepared to receive an attack. In the interval between General Stewart's departure from and return to Korti, Lord Wolseley (on the 30th December) had received from a messenger from Khartoum a communication from Gordon, showing the desperate condition of things there. The messenger brought a piece of paper the size of a postage- stamp, on which was written:—
- 48. "Khartoum all right. "(Signed) C. G. Gordon. "December 14th, 1884." It was genuine, as Gordon's writing was recognized, and his seal was on the back of it. Gordon told the messenger to give Lord Wolseley the following message:— "We are besieged on three sides, Omdurman, Halfiyeh and Khojali. Fighting goes on day and night. Enemy cannot take us, except by starving us out. Do not scatter your troops. Enemy are numerous. Bring plenty of troops if you can. We still hold Omdurman on the left bank and the fort on the right bank. The Mahdi's people have thrown up earthworks within rifle- shot of Omdurman. The Mahdi lives out of gun-shot. About four weeks ago the Mahdi's people attacked Omdurman and disabled one steamer. We disabled one of the Mahdi's guns. Three days after fighting was renewed on the south, and the rebels were again driven back. "(Secret and confidential.)—Our troops in Khartoum are suffering from lack of provisions. Food we still have is little; some grain and biscuit. We want you to come quickly. You should come by Metammeh or Berber. Make by these two roads. Do not leave Berber in your rear. Keep enemy in your front, and when you have taken Berber send me word from Berber. Do this without letting rumours of your approach spread abroad. In Khartoum there are no butter nor dates, and little meat. All food is very dear."
- 49. It is clear that the words "Khartoum all right" were simply intended to deceive in the event of the written communication getting into the wrong hands. This became evident later on from a letter which Gordon wrote to a friend in Cairo at the same date as he penned the words "Khartoum all right," but which did not arrive till the month of February. "All is up," he said; "I expect a catastrophe in ten days' time. It would not have been so if our people had kept me better informed as to their intentions. My adieux to all. C. G. Gordon." The latter part of the verbal message is significant, and seems to imply that Gordon anticipated that if the approach of the troops were to become known, the treachery which he had all along expected would be accelerated. It is scarcely necessary to say that only the written portion of Gordon's communication, viz., "Khartoum all right," was disclosed to the British public, who thus formed a very erroneous opinion as to his real position. It does not appear that Wolseley's plans were changed by the receipt of Gordon's message; there was, in fact, nothing to be done but to push on with all possible speed. On the 8th January Stewart, having strengthened his column, again set out for Gakdul. On the 10th, the force reached the Hambok wells, whence Stewart pushed forward to Howeiyah. On arriving there it was found that the Engineers and Mounted Infantry, left behind on the previous journey, had sunk several holes to a depth of nine feet or so in the rough gravel soil near a dry watercourse, and that some of these holes contained about six inches of cold opal-coloured water with a chalybeate taste. Unfortunately the holes in question had been practically drained a couple of hours before by the men of the previous convoy; so that Stewart's troops had to content themselves with only a quart per head for the entire day.
- 50. Resuming their forward march, they reached a grassy plain to the south of the Galif range shortly after sunset, and here they bivouacked until the following morning. A fresh start was then made, but the heat and excessive thirst were beginning to tell both on men and camels, thirty of the latter dropping dead on the road. However, the column persevered in its course, and the wells of Abu Haifa were reached at three in the afternoon. Pannikins, canteens, water- bottles, and horse-buckets were soon at work, the men taking their turn until their thirst was quenched. Early on the 12th the column was astir, and at eleven o'clock it defiled along a rocky gorge into the crater-like amphitheatre where the Gakdul reservoirs were situated. Here was found the force left to guard the wells when Stewart returned to Korti. It was ascertained that more wells were to be found across the hills at a distance of a mile or two, but the three natural receptacles at Gakdul itself were computed to contain among them nearly half-a-million gallons of water, so that for military purposes the supply was regarded as practically inexhaustible. Colonel Burnaby arrived at Gakdul on the 13th with a convoy of grain. The following day, the march towards Abu Klea was resumed, Major Kitchener going back to Korti, and Colonel Vandeleur being left with 400 of the Sussex Regiment at Gakdul to hold that station, whilst the Guards who had previously protected the wells joined the column. The force was composed as follows—Three troops 19th Hussars; Naval Brigade, one Gardner gun; half battery Royal Artillery, i.e., three (7-pounder) screw-guns; Heavy Camel Regiment; Guards' Camel Regiment; Mounted Infantry, Camel Regiment; Sussex Regiment; Naval Brigade Royal Engineers; Transport and Medical Corps; in all 1,581 men with 90 horses, 2,880 camels, and 340 drivers. Beyond Gakdul, the road led across a more barren region than that which had been previously traversed. Only ten miles were covered on the afternoon of the 14th.
- 51. The following day the column was again on the move at 5 a.m. When opposite Gebel-el-Nil, a well-known mountain in the desert, a halt was made to allow of the stragglers coming up. The march was now telling severely on the heavily laden camels, which had been for several days on half allowance of forage. Numbers of them fell through sheer exhaustion, and had to be shot to put them out of their misery or to prevent their falling into the hands of the enemy. At noon the march was resumed until the evening, when, after going twenty-four miles since the morning, the column halted near another mountain, Gebel Serghain. On the 16th the column started at 5 a.m. It was then too dark to see anything, and the force got into some confusion. This, however, was soon rectified on daylight appearing. Whilst halted at half-past eleven for breakfast, a report was received from Lieutenant-Colonel Barrow, of the 19th Hussars, who had been sent forward with his squadron to reconnoitre the neighbourhood of the Abu Klea wells, stating that he had seen some fifty of the enemy standing in groups on the hills about four miles north-east of Abu Klea. Shortly after this the whole force was advanced. The ground now traversed was a vast flat plain favourable for military evolutions, and the Guards' Camel Regiment, the Heavy Camel Regiment, and the Mounted Infantry Camel Regiment moved in a broad front in line of columns at half distance. Before the column rose steep black mountains through which it had to pass, and in the centre, at a point where the ground slopes towards the Nile, were the wells of Abu Klea. It soon became evident that the enemy was in force, and looking to the hour (two p.m.) Stewart deemed it undesirable to attempt an attack that day. The column, therefore, was ordered to bivouac when about three miles from Abu Klea. Abu Klea is an elevated spot in the desert, about 300 feet above the level of the Nile, distant above forty-three miles, on the caravan track, from Gakdul, and from Metammeh twenty-three miles.
- 52. On the troops bivouacking for the night the men were set to work cutting down brushwood, and forming a zeriba round, the baggage and camels. A stone breastwork with a frontage of about 150 yards was thrown up as an additional protection some 100 yards further to the front. Pickets were also placed on the hills to the left of the position. From an advanced position occupied by the outposts the enemy's camp was sighted across a pass about two miles ahead, and in front of it a long line of flags marked the position. Meanwhile two troops of the enemy were watching the movements of the British force from the hills on the left front. Towards six o'clock the enemy fired a few stray shots on the British right flank, to which three of the screw-guns replied with a few rounds. The enemy continued firing at intervals all night, with no results beyond one slight casualty.
- 53. Welcome to our website – the ideal destination for book lovers and knowledge seekers. With a mission to inspire endlessly, we offer a vast collection of books, ranging from classic literary works to specialized publications, self-development books, and children's literature. Each book is a new journey of discovery, expanding knowledge and enriching the soul of the reade Our website is not just a platform for buying books, but a bridge connecting readers to the timeless values of culture and wisdom. With an elegant, user-friendly interface and an intelligent search system, we are committed to providing a quick and convenient shopping experience. Additionally, our special promotions and home delivery services ensure that you save time and fully enjoy the joy of reading. Let us accompany you on the journey of exploring knowledge and personal growth! ebookname.com