doc/tutorial.lyx

   1 #LyX 2.0 created this file. For more info see http://www.lyx.org/
   2 \lyxformat 413
   3 \begin_document
   4 \begin_header
   5 \textclass docbook
   6 \use_default_options false
   7 \maintain_unincluded_children false
   8 \language english
   9 \language_package default
  10 \inputencoding auto
  11 \fontencoding global
  12 \font_roman default
  13 \font_sans default
  14 \font_typewriter default
  15 \font_default_family default
  16 \use_non_tex_fonts false
  17 \font_sc false
  18 \font_osf false
  19 \font_sf_scale 100
  20 \font_tt_scale 100
  21
  22 \graphics default
  23 \default_output_format default
  24 \output_sync 0
  25 \bibtex_command default
  26 \index_command default
  27 \paperfontsize default
  28 \spacing single
  29 \use_hyperref false
  30 \papersize default
  31 \use_geometry false
  32 \use_amsmath 0
  33 \use_esint 0
  34 \use_mhchem 1
  35 \use_mathdots 1
  36 \cite_engine basic
  37 \use_bibtopic false
  38 \use_indices false
  39 \paperorientation portrait
  40 \suppress_date false
  41 \use_refstyle 0
  42 \index Index
  43 \shortcut idx
  44 \color #008000
  45 \end_index
  46 \secnumdepth 3
  47 \tocdepth 3
  48 \paragraph_separation indent
  49 \paragraph_indentation default
  50 \quotes_language english
  51 \papercolumns 1
  52 \papersides 1
  53 \paperpagestyle default
  54 \tracking_changes false
  55 \output_changes false
  56 \html_math_output 0
  57 \html_css_as_file 0
  58 \html_be_strict false
  59 \end_header
  60
  61 \begin_body
  62
  63 \begin_layout Title
  64 Libpwmd Tutorial
  65 \end_layout
  66
  67 \begin_layout Date
  68 2-4-2013
  69 \end_layout
  70
  71 \begin_layout Author
  72 Ben Kibbey
  73 \begin_inset Foot
  74 status collapsed
  75
  76 \begin_layout Plain Layout
  77 bjk@luxsci.net
  78 \end_layout
  79
  80 \end_inset
  81
  82
  83 \end_layout
  84
  85 \begin_layout Author
  86 \begin_inset CommandInset toc
  87 LatexCommand tableofcontents
  88
  89 \end_inset
  90
  91
  92 \end_layout
  93
  94 \begin_layout Section
  95 Introduction
  96 \end_layout
  97
  98 \begin_layout Standard
  99 This is a tutorial showing the basic usage of libpwmd
 100 \begin_inset Foot
 101 status collapsed
 102
 103 \begin_layout Plain Layout
 104 http://libpwmd.sourceforge.net/
 105 \end_layout
 106
 107 \end_inset
 108
 109 .
 110  Libpwmd
 111 \emph on
 112
 113 \emph default
 114 is a library making it easy for applications to use pwmd
 115 \begin_inset Foot
 116 status collapsed
 117
 118 \begin_layout Plain Layout
 119 http://pwmd.sourceforge.net/
 120 \end_layout
 121
 122 \end_inset
 123
 124  (
 125 \emph on
 126 Password Manager Daemon).
 127  Password Manager Daemon
 128 \emph default
 129  is a universal data server.
 130  It began as a way to keep track of my passwords for accounts like email
 131  and websites but can be used to store anything you want.
 132 \end_layout
 133
 134 \begin_layout Standard
 135 There are other password management tools but pwmd has a couple of distinguishin
 136 g features:
 137 \end_layout
 138
 139 \begin_layout Itemize
 140 It does not depend on a desktop environment but has the ability for applications
 141  to connect to it like a desktop solution provides.
 142 \end_layout
 143
 144 \begin_layout Itemize
 145 Some portion of a stored data can be shared with another portion in the
 146  same data file.
 147  This feature behaves a lot like a symbolic link on a file system, XML entities,
 148  or HTML targets if you're familiar with those, but implemented in a different
 149  way.
 150  This means less duplication of content.
 151  See
 152 \begin_inset CommandInset ref
 153 LatexCommand ref
 154 reference "sec:Linking-elements"
 155
 156 \end_inset
 157
 158  for details.
 159 \end_layout
 160
 161 \begin_layout Itemize
 162 The XML document is encrypted with libgcrypt and can also use gpg-agent.
 163  Libgcrypt provides symmetric encryption while gpg-agent supports both PKI
 164  and smartcards.
 165 \end_layout
 166
 167 \begin_layout Standard
 168 Other features include:
 169 \end_layout
 170
 171 \begin_layout Itemize
 172 Multi-threaded.
 173  More than one client may access the same data file while optionally locking
 174  out other clients.
 175 \end_layout
 176
 177 \begin_layout Itemize
 178 Secure memory management.
 179  Pwmd will zero out memory before freeing it and the contents of the cached
 180  document are encrypted.
 181 \end_layout
 182
 183 \begin_layout Itemize
 184 Remote connections over TLS with client certificates used as authentication.
 185 \end_layout
 186
 187 \begin_layout Itemize
 188 Remote connections over SSH.
 189 \end_layout
 190
 191 \begin_layout Section
 192 File Format and Element Paths
 193 \end_layout
 194
 195 \begin_layout Standard
 196 The document is saved as an XML document and is manipulated by commands
 197  sent from a client.
 198  Commands that access data take what is called an
 199 \emph on
 200 element path
 201 \emph default
 202  as an argument.
 203  An element path is a character string containing XML element names representing
 204  branches of an element tree.
 205  The branches are separated with a TAB (ASCII 0x09) character.
 206  Why a TAB? So other characters can be used in the element name.
 207  If for example a '/' were used as the separator, then a URL (i.e., http://sf.net/)
 208  could not be used as an element name.
 209 \end_layout
 210
 211 \begin_layout Standard
 212 For the rest of this tutorial, when you see <TAB>, replace it with a real
 213  TAB character.
 214  For example, the element path "root<TAB>child<TAB>last" has the following
 215  element tree:
 216 \end_layout
 217
 218 \begin_layout Code
 219 <root>
 220 \end_layout
 221
 222 \begin_layout Code
 223     <child>
 224 \end_layout
 225
 226 \begin_layout Code
 227         <last>
 228 \end_layout
 229
 230 \begin_layout Code
 231 Content or XML CDATA of the "last" element.
 232 \end_layout
 233
 234 \begin_layout Code
 235         </last>
 236 \end_layout
 237
 238 \begin_layout Code
 239     </child>
 240 \end_layout
 241
 242 \begin_layout Code
 243 </root>
 244 \end_layout
 245
 246 \begin_layout Standard
 247 I should say that the XML structure that pwmd uses is a little more complicated.
 248  It really looks like the following internally, but we will use the above
 249  format in this tutorial for simplicity:
 250 \end_layout
 251
 252 \begin_layout Code
 253 <element _name="root">
 254 \end_layout
 255
 256 \begin_layout Code
 257     <element _name="child">
 258 \end_layout
 259
 260 \begin_layout Code
 261         <element _name="last">
 262 \end_layout
 263
 264 \begin_layout Code
 265 Content or CDATA of the "last" element.
 266 \end_layout
 267
 268 \begin_layout Code
 269         </element>
 270 \end_layout
 271
 272 \begin_layout Code
 273     </element>
 274 \end_layout
 275
 276 \begin_layout Code
 277 </element>
 278 \end_layout
 279
 280 \begin_layout Standard
 281 Every element created has an element named
 282 \emph on
 283 element
 284 \emph default
 285  with an attribute
 286 \emph on
 287 _name
 288 \emph default
 289  associated with it.
 290  The value of the
 291 \emph on
 292 _name
 293 \emph default
 294  attribute is what an element in an element path refers to.
 295  It is done this way so that a wider range of characters can be used in
 296  an element name while maintaining valid XML.
 297  In fact the only restriction of an element name is that it not contain
 298  whitespace characters and not begin with an exclamation point (ASCII 0x21
 299  or !).
 300  See
 301 \emph on
 302
 303 \begin_inset CommandInset ref
 304 LatexCommand ref
 305 reference "sec:Linking-elements"
 306
 307 \end_inset
 308
 309
 310 \emph default
 311 for an exception.
 312 \end_layout
 313
 314 \begin_layout Standard
 315 There is one other difference from your normal XML document in that only
 316  the first match of an element is considered for the current element tree
 317  depth.
 318  When an element of the current depth of an element tree is found, the next
 319  element in the element path is searched for beginning at the child node
 320  of the found element.
 321  From the example above:
 322 \end_layout
 323
 324 \begin_layout Code
 325 <root>
 326 \end_layout
 327
 328 \begin_layout Code
 329     <child>
 330 \end_layout
 331
 332 \begin_layout Code
 333         <last>
 334 \end_layout
 335
 336 \begin_layout Code
 337 Content or XML CDATA of the "last" element.
 338 \end_layout
 339
 340 \begin_layout Code
 341         </last>
 342 \end_layout
 343
 344 \begin_layout Code
 345     </child>
 346 \end_layout
 347
 348 \begin_layout Code
 349     <child>
 350 \end_layout
 351
 352 \begin_layout Code
 353 This element will never be reached.
 354 \end_layout
 355
 356 \begin_layout Code
 357     </child>
 358 \end_layout
 359
 360 \begin_layout Code
 361 </root>
 362 \end_layout
 363
 364 \begin_layout Standard
 365 The second "child" element is never reached.
 366 \end_layout
 367
 368 \begin_layout Section
 369 Connecting to PWMD
 370 \end_layout
 371
 372 \begin_layout Standard
 373 You will need a
 374 \emph on
 375 pwmd
 376 \emph default
 377  client to send commands to the pwmd server.
 378
 379 \emph on
 380 libpwmd
 381 \emph default
 382  includes a client named
 383 \emph on
 384 pwmc
 385 \emph default
 386 .
 387  It is command-line based and there are not any fancy graphics, but it is
 388  good for understanding how
 389 \emph on
 390 pwmd
 391 \emph default
 392  commands are processed.
 393  If you want a more user friendly client that resembles a file manager and
 394  has a point and click interface, try QPwmc
 395 \begin_inset Foot
 396 status collapsed
 397
 398 \begin_layout Plain Layout
 399 http://qpwmc.sourceforge.net/
 400 \end_layout
 401
 402 \end_inset
 403
 404  which uses the Qt4 toolkit and is also a full featured client.
 405 \end_layout
 406
 407 \begin_layout Standard
 408 In this tutorial we will use the
 409 \emph on
 410 pwmc
 411 \emph default
 412  client included with libpwmd.
 413
 414 \emph on
 415 pwmc
 416 \emph default
 417  has two modes that commands are read from: interactive and stdin.
 418  The interactive mode uses the readline library and has command history,
 419  while reading from standard input (stdin) makes shell scripting and automation
 420  easy.
 421  For the examples, we will be connecting to the default local unix domain
 422  socket that pwmd waits for connections on.
 423  Remote connections are possible over TLS or an SSH channel but those are
 424  not covered here.
 425  Read the pwmc(1) manual page for details about how to do that.
 426 \end_layout
 427
 428 \begin_layout Standard
 429 The example filename we will use is "datafile".
 430  It is initially a non-existent file but it will be created once we have
 431  saved to it.
 432  Now let us connect to the server in interactive mode and open the data
 433  file:
 434 \end_layout
 435
 436 \begin_layout Code
 437 $ pwmc datafile
 438 \end_layout
 439
 440 \begin_layout Code
 441 Connected.
 442 \end_layout
 443
 444 \begin_layout Code
 445 pwm>
 446 \end_layout
 447
 448 \begin_layout Standard
 449 The "pwm>" prompt is a readline prompt that has command history and can
 450  do filename completion.
 451  It also is annoying because, as mentioned, elements in element paths are
 452  TAB delimited, but command completion in readline uses the TAB character,
 453  too.
 454  To insert a real TAB character in interactive mode rather than do readline
 455  completion, you will need to first press CTRL-V and then press TAB.
 456 \end_layout
 457
 458 \begin_layout Section
 459 Commands
 460 \end_layout
 461
 462 \begin_layout Standard
 463 There are two different types of commands: client commands and protocol
 464  commands.
 465  The client commands are
 466 \emph on
 467 pwmc
 468 \emph default
 469  specific and only available to the
 470 \emph on
 471 pwmc
 472 \emph default
 473  client.
 474  Protocol commands are commands sent from any client and to the
 475 \emph on
 476 pwmd
 477 \emph default
 478  server.
 479  All pwmc client commands are prefixed with a dot '.' followed by the command
 480  name.
 481  Protocol commands are sent without any prefix.
 482  To see the available pwmc and protocol commands, send the HELP command:
 483 \end_layout
 484
 485 \begin_layout Code
 486 pwm> .help
 487 \end_layout
 488
 489 \begin_layout Standard
 490 or
 491 \end_layout
 492
 493 \begin_layout Code
 494 pwm> help
 495 \end_layout
 496
 497 \begin_layout Standard
 498 To store some data in an element path, you will need to know what element
 499  path to create.
 500  It is up to you how you want your data organized.
 501  If for example you will be storing account information it may be good to
 502  categorize what the account is for: email, instant messaging, blogging,
 503  etc.
 504  An application that uses libpwmd may require that a certain element path
 505  exists.
 506  Refer to that applications documentation to determine what element paths
 507  need to be created.
 508 \end_layout
 509
 510 \begin_layout Standard
 511 In the following example we will setup mail server element paths which can
 512  be used for other applications requiring a mail server configuration.
 513  First, lets create the hostname element path:
 514 \end_layout
 515
 516 \begin_layout Code
 517 pwm> STORE
 518 \end_layout
 519
 520 \begin_layout Standard
 521 The STORE command is a
 522 \emph on
 523 pwmd
 524 \emph default
 525  protocol command.
 526  This and a few other commands, use what is called a
 527 \emph on
 528 server inquire
 529 \emph default
 530  to retrieve data from the client while other commands retrieve the data
 531  only from the command arguments.
 532  The server inquire will wait for the client to finish sending its data
 533  before completing the command.
 534  When responding to a server inquire in pwmc, pwmc will show a message telling
 535  you that it is waiting for data to be sent.
 536  Enter the element path and its content, then press <CTRL-D> twice to finish
 537  sending the data and to let
 538 \emph on
 539 pwmd
 540 \emph default
 541  complete the command:
 542 \end_layout
 543
 544 \begin_layout Code
 545 pwm> STORE
 546 \end_layout
 547
 548 \begin_layout Code
 549 email<TAB>isp<TAB>IMAP<TAB>hostname<TAB>imap.server.com<CTRL-D><CTRL-D>
 550 \end_layout
 551
 552 \begin_layout Standard
 553 Remember that you should replace <TAB> in the examples with a real TAB character.
 554  It should be known that when sending data via a server inquire there is
 555  no need to press <CTRL-V> to insert the <TAB> character.
 556  That is only needed to be done from the readline command prompt and when
 557  not doing a server inquire.
 558 \end_layout
 559
 560 \begin_layout Standard
 561 After pressing the first <CTRL-D>, the characters that were entered are
 562  sent to
 563 \emph on
 564 pwmd
 565 \emph default
 566  and the inquire continues.
 567  To terminate the inquire and finish sending data for the command press
 568  <CTRL-D> a second time.
 569 \end_layout
 570
 571 \begin_layout Standard
 572 If you were to have pressed <RETURN> before any <CTRL-D> then the inquired
 573  line would have been sent in full including a newline character.
 574  Since in this example a newline character in a hostname is not a valid
 575  hostname, this is not what we want.
 576 \end_layout
 577
 578 \begin_layout Standard
 579 We have just created an element path whose XML structure looks like the
 580  following:
 581 \end_layout
 582
 583 \begin_layout Code
 584 <email>
 585 \end_layout
 586
 587 \begin_layout Code
 588     <isp>
 589 \end_layout
 590
 591 \begin_layout Code
 592         <IMAP>
 593 \end_layout
 594
 595 \begin_layout Code
 596             <hostname>imap.server.com</hostname>
 597 \end_layout
 598
 599 \begin_layout Code
 600         </IMAP>
 601 \end_layout
 602
 603 \begin_layout Code
 604     </isp>
 605 \end_layout
 606
 607 \begin_layout Code
 608 </email>
 609 \end_layout
 610
 611 \begin_layout Standard
 612 The GET protocol command returns the value, or content, of the last element
 613  of an element path.
 614  To retrieve the hostname of the element path we just created, do:
 615 \end_layout
 616
 617 \begin_layout Code
 618 pwm> GET email<TAB>isp<TAB>IMAP<TAB>hostname
 619 \end_layout
 620
 621 \begin_layout Code
 622 imap.server.com
 623 \end_layout
 624
 625 \begin_layout Standard
 626 Remember that in interactive mode and when not doing a server inquire, you
 627  will need to press <CTRL-V> before pressing <TAB>.
 628 \end_layout
 629
 630 \begin_layout Standard
 631 Let us create the rest of the needed elements:
 632 \end_layout
 633
 634 \begin_layout Code
 635 pwm> STORE
 636 \end_layout
 637
 638 \begin_layout Code
 639 email<TAB>isp<TAB>IMAP<TAB>port<TAB>993<CTRL-D><CTRL-D>
 640 \end_layout
 641
 642 \begin_layout Code
 643 pwm> STORE
 644 \end_layout
 645
 646 \begin_layout Code
 647 email<TAB>isp<TAB>IMAP<TAB>ssl<TAB>1<CTRL-D><CTRL-D>
 648 \end_layout
 649
 650 \begin_layout Code
 651 pwm> STORE
 652 \end_layout
 653
 654 \begin_layout Code
 655 email<TAB>isp<TAB>username<TAB>myusername<CTRL-D><CTRL-D>
 656 \end_layout
 657
 658 \begin_layout Code
 659 pwm> STORE
 660 \end_layout
 661
 662 \begin_layout Code
 663 email<TAB>isp<TAB>password<TAB>mypassword<CTRL-D><CTRL-D>
 664 \end_layout
 665
 666 \begin_layout Standard
 667 Now the element structure for the "email" element looks like this:
 668 \end_layout
 669
 670 \begin_layout Code
 671 <email>
 672 \end_layout
 673
 674 \begin_layout Code
 675     <isp>
 676 \end_layout
 677
 678 \begin_layout Code
 679         <IMAP>
 680 \end_layout
 681
 682 \begin_layout Code
 683               <hostname>imap.server.com</hostname>
 684 \end_layout
 685
 686 \begin_layout Code
 687               <port>993</port>
 688 \end_layout
 689
 690 \begin_layout Code
 691               <ssl>1</ssl>
 692 \end_layout
 693
 694 \begin_layout Code
 695         </IMAP>
 696 \end_layout
 697
 698 \begin_layout Code
 699         <username>myusername</username>
 700 \end_layout
 701
 702 \begin_layout Code
 703         <password>mypassword</password>
 704 \end_layout
 705
 706 \begin_layout Code
 707     </isp>
 708 \end_layout
 709
 710 \begin_layout Code
 711 </email>
 712 \end_layout
 713
 714 \begin_layout Standard
 715 If you wanted to change your password (after changing it on the mail server,
 716  of course) just do as you did when initially creating the password element
 717  path.
 718  The new content will overwrite the existing content:
 719 \end_layout
 720
 721 \begin_layout Code
 722 pwm> STORE
 723 \end_layout
 724
 725 \begin_layout Code
 726 email<TAB>isp<TAB>password<TAB>newpassword<CTRL-D><CTRL-D>
 727 \end_layout
 728
 729 \begin_layout Standard
 730 An application using libpwmd that needs to know mail server information
 731  now has all the information it needs.
 732  The only thing left to do now is to save the changes:
 733 \end_layout
 734
 735 \begin_layout Code
 736 pwm> <CTRL-D>
 737 \end_layout
 738
 739 \begin_layout Standard
 740 After pressing <CTRL-D> a prompt will be shown asking what to do next.
 741  Press
 742 \begin_inset Quotes eld
 743 \end_inset
 744
 745 s
 746 \begin_inset Quotes erd
 747 \end_inset
 748
 749  to save what we have created.
 750 \end_layout
 751
 752 \begin_layout Standard
 753 Since this is a new file, you will be prompted for a passphrase to use for
 754  encryption.
 755  Once done, the data file is encrypted and written to disk and the passphrase
 756  is cached in pwmd so you do not need to enter it the next time your data
 757  file is opened or saved.
 758  There are a few pwmd configuration parameters and commands that affect
 759  how this operates.
 760  See the
 761 \emph on
 762 pwmd
 763 \emph default
 764  documentation for details.
 765 \end_layout
 766
 767 \begin_layout Section
 768 \begin_inset CommandInset label
 769 LatexCommand label
 770 name "sec:Linking-elements"
 771
 772 \end_inset
 773
 774 Linking elements
 775 \end_layout
 776
 777 \begin_layout Standard
 778 One distinguishing feature of pwmd is the ability to share data of one element
 779  path with another.
 780  If for example your ISP lets you host a blog on their server and you use
 781  a blogging client that can use libpwmd for authentication details, you
 782  can share authentication information with the email example above when
 783  the account details are the same.
 784  When element linking is used, this avoids the need to change the content
 785  for both the blogging and email password elements.
 786 \end_layout
 787
 788 \begin_layout Standard
 789 This is done by setting a special
 790 \begin_inset Quotes eld
 791 \end_inset
 792
 793 target
 794 \begin_inset Quotes erd
 795 \end_inset
 796
 797  attribute for an element.
 798  It behaves similarly to the HTML
 799 \begin_inset Quotes eld
 800 \end_inset
 801
 802 target
 803 \begin_inset Quotes erd
 804 \end_inset
 805
 806  attribute or XML entities or a symbolic link on a filesystem.
 807
 808 \end_layout
 809
 810 \begin_layout Standard
 811 Let's create an example blogging element path:
 812 \end_layout
 813
 814 \begin_layout Code
 815 pwm> STORE
 816 \end_layout
 817
 818 \begin_layout Code
 819 blog<TAB>isp<TAB>hostname<TAB>blog.myisp.com<CTRL-D><CTRL-D>
 820 \end_layout
 821
 822 \begin_layout Code
 823
 824 \end_layout
 825
 826 \begin_layout Code
 827 pwm> ATTR SET target blog<TAB>isp<TAB>username email<TAB>isp<TAB>username
 828 \end_layout
 829
 830 \begin_layout Code
 831 pwm> ATTR SET target blog<TAB>isp<TAB>password email<TAB>isp<TAB>password
 832 \end_layout
 833
 834 \begin_layout Standard
 835 Now each access of the "blog/isp/username" and "blog/isp/password" element
 836  paths, which were created if they did not already exist, will point to
 837  "email/isp/username" and "email/isp/password", respectively.
 838  To retrieve the value or content of an element that contains a "target"
 839  attribute without following any
 840 \begin_inset Quotes eld
 841 \end_inset
 842
 843 target
 844 \begin_inset Quotes erd
 845 \end_inset
 846
 847  attribute, prefix the element with a '!' when specifying it in an element
 848  path.
 849  For example:
 850 \end_layout
 851
 852 \begin_layout Code
 853 pwm> GET blog<TAB>isp<TAB>!password
 854 \end_layout
 855
 856 \begin_layout Code
 857 ERR 536870938: No value
 858 \end_layout
 859
 860 \begin_layout Standard
 861 An error is returned because we have not assigned a value to the literal
 862  element.
 863  A literal element is an element that either contains no "target" attribute
 864  or ignores it by prefixing the element with the mentioned literal element
 865  character '!'.
 866  Let us try storing an example password to the literal element to show usage:
 867 \end_layout
 868
 869 \begin_layout Code
 870 pwmd> STORE
 871 \end_layout
 872
 873 \begin_layout Code
 874 blog<TAB>isp<TAB>!password<TAB>literalpassword<CTRL-D><CTRL-D>
 875 \end_layout
 876
 877 \begin_layout Standard
 878 Now when we redo the previous GET command:
 879 \end_layout
 880
 881 \begin_layout Code
 882 pwm> GET blog<TAB>isp<TAB>!password
 883 \end_layout
 884
 885 \begin_layout Code
 886 literalpassword
 887 \end_layout
 888
 889 \begin_layout Standard
 890 This is the value of the literal password element of the element path.
 891  To follow the element path stored in the "target" attribute, omit the '!'
 892  in the password element.
 893  This will return the
 894 \begin_inset Quotes eld
 895 \end_inset
 896
 897 email/isp/password
 898 \begin_inset Quotes erd
 899 \end_inset
 900
 901  element content:
 902 \end_layout
 903
 904 \begin_layout Code
 905 pwm> GET blog<TAB>isp<TAB>password
 906 \end_layout
 907
 908 \begin_layout Code
 909 mypassword
 910 \end_layout
 911
 912 \begin_layout Standard
 913 A "target" attribute may also refer to another element with a "target" attribute.
 914  Every "target" attribute will be followed until there are no others to
 915  resolve.
 916  To get the real element path and resolve all "target" attributes, use the
 917  REALPATH command:
 918 \end_layout
 919
 920 \begin_layout Code
 921 pwm> REALPATH blog<TAB>isp<TAB>password
 922 \end_layout
 923
 924 \begin_layout Code
 925 !email<TAB>!isp<TAB>!password
 926 \end_layout
 927
 928 \begin_layout Standard
 929 As you can see each element is prefixed with the literal '!' character meaning
 930  that no "target" attribute exists in any element of the resulting element
 931  path.
 932 \end_layout
 933
 934 \begin_layout Standard
 935 Using the LIST command is useful to show the element structure of a document:
 936 \end_layout
 937
 938 \begin_layout Code
 939 pwm> LIST
 940 \end_layout
 941
 942 \begin_layout Code
 943 !email
 944 \end_layout
 945
 946 \begin_layout Code
 947 !blog
 948 \end_layout
 949
 950 \begin_layout Code
 951 pwm> LIST !email
 952 \end_layout
 953
 954 \begin_layout Code
 955 !email
 956 \end_layout
 957
 958 \begin_layout Code
 959 !email<TAB>!isp
 960 \end_layout
 961
 962 \begin_layout Code
 963 !email<TAB>!isp<TAB>!username
 964 \end_layout
 965
 966 \begin_layout Code
 967 !email<TAB>!isp<TAB>!password
 968 \end_layout
 969
 970 \begin_layout Code
 971 !email<TAB>!isp<TAB>!IMAP<TAB>!hostname
 972 \end_layout
 973
 974 \begin_layout Code
 975 !email<TAB>!isp<TAB>!IMAP<TAB>!port
 976 \end_layout
 977
 978 \begin_layout Code
 979 !email<TAB>!isp<TAB>!IMAP<TAB>!ssl
 980 \end_layout
 981
 982 \begin_layout Code
 983 pwm> LIST !blog
 984 \end_layout
 985
 986 \begin_layout Code
 987 !blog
 988 \end_layout
 989
 990 \begin_layout Code
 991 !blog<TAB>!isp
 992 \end_layout
 993
 994 \begin_layout Code
 995 !blog<TAB>!isp<TAB>!username
 996 \end_layout
 997
 998 \begin_layout Code
 999 !blog<TAB>!isp<TAB>username
1000 \end_layout
1001
1002 \begin_layout Code
1003 !blog<TAB>!isp<TAB>!password
1004 \end_layout
1005
1006 \begin_layout Code
1007 !blog<TAB>!isp<TAB>password
1008 \end_layout
1009
1010 \begin_layout Standard
1011 Notice that there are two username and password elements in the
1012 \begin_inset Quotes eld
1013 \end_inset
1014
1015 blog
1016 \begin_inset Quotes erd
1017 \end_inset
1018
1019  element path: each with and without the literal element character prefix.
1020  This shows that both the username and password elements contain a "target"
1021  attribute.
1022 \end_layout
1023
1024 \begin_layout Standard
1025 For the final example, we will remove the
1026 \begin_inset Quotes eld
1027 \end_inset
1028
1029 target
1030 \begin_inset Quotes erd
1031 \end_inset
1032
1033  attribute of the blogging password element:
1034 \end_layout
1035
1036 \begin_layout Code
1037 pwm> ATTR DELETE target blog<TAB>isp<TAB>!password
1038 \end_layout
1039
1040 \begin_layout Standard
1041 If we were to have omitted the '!' from the password element then pwmd would
1042  try to remove the "target" attribute from the "email/isp/password" element
1043  path.
1044  That would return an error because no
1045 \begin_inset Quotes eld
1046 \end_inset
1047
1048 target
1049 \begin_inset Quotes erd
1050 \end_inset
1051
1052  attribute had been set for that element.
1053 \end_layout
1054
1055 \begin_layout Standard
1056 Note that the "blog" and "isp" elements have no literal element character
1057  prepended to them in the example.
1058  It is not needed because they have no
1059 \begin_inset Quotes eld
1060 \end_inset
1061
1062 target
1063 \begin_inset Quotes erd
1064 \end_inset
1065
1066  attribute themselves.
1067 \end_layout
1068
1069 \begin_layout Standard
1070 Using
1071 \begin_inset Quotes eld
1072 \end_inset
1073
1074 target
1075 \begin_inset Quotes erd
1076 \end_inset
1077
1078  attributes can be confusing.
1079  The best way to get the hang of linking elements is to experiment and use
1080  the LIST and DUMP commands to show the document structure.
1081  Remember to use the literal element prefix '!' when you do not want to
1082  follow any "target" attributes.
1083 \end_layout
1084
1085 \end_body
1086 \end_document