diff --git a/docu/mars-user-manual.lyx b/docu/mars-user-manual.lyx index 4c887d18..e14740c8 100644 --- a/docu/mars-user-manual.lyx +++ b/docu/mars-user-manual.lyx @@ -27477,302 +27477,6 @@ name "sec:The-macro-processor" \end_inset -\end_layout - -\begin_layout Chapter -Troubleshooting -\end_layout - -\begin_layout Standard -TBD: appendices.... -\end_layout - -\begin_layout Part -Old Structure (TO DISAPPEAR) -\end_layout - -\begin_layout Chapter -Quick Start Guide -\end_layout - -\begin_layout Section -The State of MARS -\begin_inset CommandInset label -LatexCommand label -name "sec:The-State-of" - -\end_inset - - -\end_layout - -\begin_layout Standard -In general, MARS tries to -\emph on -hide -\emph default - any network failures from you as best as it can. - After a network problem, any internal low-level socket connections are - -\emph on -transparently -\emph default - tried to re-open ASAP, without need for sysadmin intervention. - In difference to DRBD, network failures will -\emph on -not -\emph default - automatically alter the state of MARS, such as switching to -\family typewriter -disconnected -\family default - after a -\family typewriter -ko_timeout -\family default - or similar. - From a high-level sysadmin viewpoint, communication may just take a very - long time to succeed. -\end_layout - -\begin_layout Standard -When the behaviour of MARS is different from DRBD, it is usually intended - as a feature. -\end_layout - -\begin_layout Standard -MARS is not only an -\series bold -asynchronous -\series default - system at block IO level, but also -\series bold -at control level -\series default -. -\end_layout - -\begin_layout Standard -This is -\emph on -necessary -\emph default - because in a widely distributed long-distance system running on slow or - even temporarily failing networks, actions may take a long time, and there - may be many actions -\series bold -started in parallel -\series default -. -\end_layout - -\begin_layout Standard -\begin_inset Graphics - filename images/lightbulb_brightlit_benj_.png - lyxscale 12 - scale 7 - -\end_inset - -Synchronous concepts are generally not sufficient for expressing that. - Because of inherent asynchronicity and of dynamic creation / joining of - resources, it is neither possible to comprehensively depict a complex distribut -ed MARS system, nor a comprehensive standalone snippet of MARS, as a finite - state transition diagram -\begin_inset Foot -status open - -\begin_layout Plain Layout -Probably it could be possible to formally model MARS as a Petri net. - However, complete Petri nets are tending to become very conplex, and to - describe lots of low-level details. - Expressing hierarchy, in a top-down fashion, is cumbersome. - We find no clue in trying to do so. -\end_layout - -\end_inset - -. -\end_layout - -\begin_layout Standard -Although MARS tries to -\emph on -approximate -\emph default - / -\emph on -emulate -\emph default - the synchronous control behaviour of DRBD at the interface level ( -\family typewriter -marsadm -\family default -) in many situations as best as it can, the -\emph on -internal -\emph default - control model is necessarily asynchronous. - As an experiencend sysadmin, you will be curious how it works in principle. - When you know something about it, you will no longer be surprised when - some (detail) behaviour is different from DRBD. -\end_layout - -\begin_layout Standard -The general principle is an asynchronous 2-edge handshake protocol, which - is used almost everywhere in MARS: -\begin_inset Separator latexpar -\end_inset - - -\end_layout - -\begin_layout Standard -\noindent -\align center -\begin_inset Graphics - filename images/handshake.fig - width 80col% - -\end_inset - - -\end_layout - -\begin_layout Standard -We have a binary todo switch, which can be either in state -\begin_inset Quotes eld -\end_inset - -on -\begin_inset Quotes erd -\end_inset - - or -\begin_inset Quotes eld -\end_inset - -off -\begin_inset Quotes erd -\end_inset - -. - In addition, we have an actual response indicator, which is similar to - an LED indicating the actual status. - In our example, we imagine that both are used for controlling a big ventilator, - having a huge inert mass. - Imagine a big machine from a power plant, which is as tall as a human. -\end_layout - -\begin_layout Standard -We start in a situation where the binary switch is off, and the ventilator - is stopped. - At point 1, we turn on the switch. - At that moment, a big contactor will sound like -\begin_inset Quotes eld -\end_inset - -zonggg -\begin_inset Quotes erd -\end_inset - -, and a big motor will start to hum. - At first you won't hear anything else. - It will take a while, say 1 minute, until the big wheel will have reached - its final operating RPM, due to the huge inert mass. - During that spin-up, the lights in your room will become slightly darker. - When having reached the full RPM at point 2, your workplace will then be - noisier, but in exchange your room lights will be back at ordinary strength, - and the actual response LED will start to lit in order to indicate that - the big fan is now operational. -\end_layout - -\begin_layout Standard -Assume we want to turn the system off. - When turning the todo switch to -\begin_inset Quotes eld -\end_inset - -off -\begin_inset Quotes erd -\end_inset - - at point 3, first nothing will seem to happen at all. - The big wheel will keep spinning due to its heavy inert mass, and the RPM - as well as the sound will go down only slowly. - During spin-down, the actual response LED will stay illuminated, in order - to warn you that you should not touch the wheel, otherwise you may get - injuried -\begin_inset Foot -status open - -\begin_layout Plain Layout -Notice that it is only safe to access the wheel when -\emph on -both -\emph default - the switch and the LED are off. - Conversely, if at least one of them is on, something is going on inside - the machine. - Transferred to MARS: always look at -\emph on -both -\emph default - the todo switch and the correponding actual indicator in order to not miss - something. -\end_layout - -\end_inset - -. - The LED will only go off after, say, 2 minutes, when the wheel has actually - stopped at point 4. - After that, the cycle may potentially start over again. -\end_layout - -\begin_layout Standard -As you can see, all four possible cartesian product combinations between - two boolean values are occurring in the diagram. -\end_layout - -\begin_layout Standard -The same handshake protocol is used in MARS for communication between userspace - and kernelspace, as well as for communication in the widely distributed - system. -\end_layout - -\begin_layout Chapter -Basic Working Principle -\end_layout - -\begin_layout Standard -Even if you are impatient, please read this chapter. - At the -\emph on -surface -\emph default -, MARS appears to be very similar to DRBD. - It looks like almost being a drop-in replacement for DRBD. -\end_layout - -\begin_layout Standard -When taking this naïvely, you could easily step into some trivial pitfalls, - because the internal working principle of MARS is totally different from - DRBD. - Please forget (almost) anything you already know about the internal working - principles of DRBD, and look at the very different working principles of - MARS. -\end_layout - -\begin_layout Chapter -The Macro Processor -\begin_inset CommandInset label -LatexCommand label -name "chap:The-Macro-Processor" - -\end_inset - - \end_layout \begin_layout Standard @@ -32032,6 +31736,302 @@ Same as the firmly built in. \end_layout +\begin_layout Chapter +Troubleshooting +\end_layout + +\begin_layout Standard +TBD: appendices.... +\end_layout + +\begin_layout Part +Old Structure (TO DISAPPEAR) +\end_layout + +\begin_layout Chapter +Quick Start Guide +\end_layout + +\begin_layout Section +The State of MARS +\begin_inset CommandInset label +LatexCommand label +name "sec:The-State-of" + +\end_inset + + +\end_layout + +\begin_layout Standard +In general, MARS tries to +\emph on +hide +\emph default + any network failures from you as best as it can. + After a network problem, any internal low-level socket connections are + +\emph on +transparently +\emph default + tried to re-open ASAP, without need for sysadmin intervention. + In difference to DRBD, network failures will +\emph on +not +\emph default + automatically alter the state of MARS, such as switching to +\family typewriter +disconnected +\family default + after a +\family typewriter +ko_timeout +\family default + or similar. + From a high-level sysadmin viewpoint, communication may just take a very + long time to succeed. +\end_layout + +\begin_layout Standard +When the behaviour of MARS is different from DRBD, it is usually intended + as a feature. +\end_layout + +\begin_layout Standard +MARS is not only an +\series bold +asynchronous +\series default + system at block IO level, but also +\series bold +at control level +\series default +. +\end_layout + +\begin_layout Standard +This is +\emph on +necessary +\emph default + because in a widely distributed long-distance system running on slow or + even temporarily failing networks, actions may take a long time, and there + may be many actions +\series bold +started in parallel +\series default +. +\end_layout + +\begin_layout Standard +\begin_inset Graphics + filename images/lightbulb_brightlit_benj_.png + lyxscale 12 + scale 7 + +\end_inset + +Synchronous concepts are generally not sufficient for expressing that. + Because of inherent asynchronicity and of dynamic creation / joining of + resources, it is neither possible to comprehensively depict a complex distribut +ed MARS system, nor a comprehensive standalone snippet of MARS, as a finite + state transition diagram +\begin_inset Foot +status open + +\begin_layout Plain Layout +Probably it could be possible to formally model MARS as a Petri net. + However, complete Petri nets are tending to become very conplex, and to + describe lots of low-level details. + Expressing hierarchy, in a top-down fashion, is cumbersome. + We find no clue in trying to do so. +\end_layout + +\end_inset + +. +\end_layout + +\begin_layout Standard +Although MARS tries to +\emph on +approximate +\emph default + / +\emph on +emulate +\emph default + the synchronous control behaviour of DRBD at the interface level ( +\family typewriter +marsadm +\family default +) in many situations as best as it can, the +\emph on +internal +\emph default + control model is necessarily asynchronous. + As an experiencend sysadmin, you will be curious how it works in principle. + When you know something about it, you will no longer be surprised when + some (detail) behaviour is different from DRBD. +\end_layout + +\begin_layout Standard +The general principle is an asynchronous 2-edge handshake protocol, which + is used almost everywhere in MARS: +\begin_inset Separator latexpar +\end_inset + + +\end_layout + +\begin_layout Standard +\noindent +\align center +\begin_inset Graphics + filename images/handshake.fig + width 80col% + +\end_inset + + +\end_layout + +\begin_layout Standard +We have a binary todo switch, which can be either in state +\begin_inset Quotes eld +\end_inset + +on +\begin_inset Quotes erd +\end_inset + + or +\begin_inset Quotes eld +\end_inset + +off +\begin_inset Quotes erd +\end_inset + +. + In addition, we have an actual response indicator, which is similar to + an LED indicating the actual status. + In our example, we imagine that both are used for controlling a big ventilator, + having a huge inert mass. + Imagine a big machine from a power plant, which is as tall as a human. +\end_layout + +\begin_layout Standard +We start in a situation where the binary switch is off, and the ventilator + is stopped. + At point 1, we turn on the switch. + At that moment, a big contactor will sound like +\begin_inset Quotes eld +\end_inset + +zonggg +\begin_inset Quotes erd +\end_inset + +, and a big motor will start to hum. + At first you won't hear anything else. + It will take a while, say 1 minute, until the big wheel will have reached + its final operating RPM, due to the huge inert mass. + During that spin-up, the lights in your room will become slightly darker. + When having reached the full RPM at point 2, your workplace will then be + noisier, but in exchange your room lights will be back at ordinary strength, + and the actual response LED will start to lit in order to indicate that + the big fan is now operational. +\end_layout + +\begin_layout Standard +Assume we want to turn the system off. + When turning the todo switch to +\begin_inset Quotes eld +\end_inset + +off +\begin_inset Quotes erd +\end_inset + + at point 3, first nothing will seem to happen at all. + The big wheel will keep spinning due to its heavy inert mass, and the RPM + as well as the sound will go down only slowly. + During spin-down, the actual response LED will stay illuminated, in order + to warn you that you should not touch the wheel, otherwise you may get + injuried +\begin_inset Foot +status open + +\begin_layout Plain Layout +Notice that it is only safe to access the wheel when +\emph on +both +\emph default + the switch and the LED are off. + Conversely, if at least one of them is on, something is going on inside + the machine. + Transferred to MARS: always look at +\emph on +both +\emph default + the todo switch and the correponding actual indicator in order to not miss + something. +\end_layout + +\end_inset + +. + The LED will only go off after, say, 2 minutes, when the wheel has actually + stopped at point 4. + After that, the cycle may potentially start over again. +\end_layout + +\begin_layout Standard +As you can see, all four possible cartesian product combinations between + two boolean values are occurring in the diagram. +\end_layout + +\begin_layout Standard +The same handshake protocol is used in MARS for communication between userspace + and kernelspace, as well as for communication in the widely distributed + system. +\end_layout + +\begin_layout Chapter +Basic Working Principle +\end_layout + +\begin_layout Standard +Even if you are impatient, please read this chapter. + At the +\emph on +surface +\emph default +, MARS appears to be very similar to DRBD. + It looks like almost being a drop-in replacement for DRBD. +\end_layout + +\begin_layout Standard +When taking this naïvely, you could easily step into some trivial pitfalls, + because the internal working principle of MARS is totally different from + DRBD. + Please forget (almost) anything you already know about the internal working + principles of DRBD, and look at the very different working principles of + MARS. +\end_layout + +\begin_layout Chapter +The Macro Processor +\begin_inset CommandInset label +LatexCommand label +name "chap:The-Macro-Processor" + +\end_inset + + +\end_layout + \begin_layout Section Scripting HOWTO \begin_inset CommandInset label