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 6-2-2012
  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 document is encrypted with GnuPG and uses gpg-agent for passphrase handling.
 163  GnuPG supports both symmetric and PKI encryption and smartcards are also
 164  supported.
 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 Section
 188 File Format and Element Paths
 189 \end_layout
 190
 191 \begin_layout Standard
 192 The document is saved as an XML document and is manipulated by commands
 193  sent from a client.
 194  Commands that access data take what is called an
 195 \emph on
 196 element path
 197 \emph default
 198  as an argument.
 199  An element path is a character string containing XML element names representing
 200  branches of an element tree.
 201  The branches are separated with a TAB (ASCII 0x09) character.
 202  Why a TAB? So other characters can be used in the element name.
 203  If for example a '/' were used as the separator, then a URL (i.e., http://sf.net/)
 204  could not be used as an element name.
 205 \end_layout
 206
 207 \begin_layout Standard
 208 For the rest of this tutorial, when you see <TAB>, replace it with a real
 209  TAB character.
 210  For example, the element path "a<TAB>child<TAB>last" has the following
 211  element tree:
 212 \end_layout
 213
 214 \begin_layout Code
 215
 216 <root>
 217 \end_layout
 218
 219 \begin_layout Code
 220
 221     <child>
 222 \end_layout
 223
 224 \begin_layout Code
 225
 226         <last>
 227 \end_layout
 228
 229 \begin_layout Code
 230
 231 Content or XML CDATA of the "last" element.
 232 \end_layout
 233
 234 \begin_layout Code
 235
 236         </last>
 237 \end_layout
 238
 239 \begin_layout Code
 240
 241     </child>
 242 \end_layout
 243
 244 \begin_layout Code
 245
 246 </root>
 247 \end_layout
 248
 249 \begin_layout Standard
 250 I should say that the XML structure that pwmd uses is a little more complicated.
 251  It really looks like the following internally, but we will use the above
 252  format in this tutorial for simplicity:
 253 \end_layout
 254
 255 \begin_layout Code
 256
 257 <element _name="root">
 258 \end_layout
 259
 260 \begin_layout Code
 261
 262     <element _name="child">
 263 \end_layout
 264
 265 \begin_layout Code
 266
 267         <element _name="last">
 268 \end_layout
 269
 270 \begin_layout Code
 271
 272 Content or CDATA of the "last" element.
 273 \end_layout
 274
 275 \begin_layout Code
 276
 277         </element>
 278 \end_layout
 279
 280 \begin_layout Code
 281
 282     </element>
 283 \end_layout
 284
 285 \begin_layout Code
 286
 287 </element>
 288 \end_layout
 289
 290 \begin_layout Standard
 291 Every element created has an element named
 292 \emph on
 293 element
 294 \emph default
 295  with an attribute
 296 \emph on
 297 _name
 298 \emph default
 299  associated with it.
 300  The value of the
 301 \emph on
 302 _name
 303 \emph default
 304  attribute is what an element in an element path refers to.
 305  It is done this way so that a wider range of characters can be used in
 306  an element name while maintaining valid XML.
 307  In fact, the only restriction of an element name is that it not contain
 308  whitespace characters and not begin with an exclamation point (ASCII 0x21
 309  or !).
 310  See
 311 \emph on
 312
 313 \begin_inset CommandInset ref
 314 LatexCommand ref
 315 reference "sec:Linking-elements"
 316
 317 \end_inset
 318
 319
 320 \emph default
 321 for an exception.
 322 \end_layout
 323
 324 \begin_layout Standard
 325 There is one other difference from your normal XML document in that only
 326  the first match of an element is considered for the current element tree
 327  depth.
 328  When an element of the current depth of an element tree is found, the next
 329  element in the element path is searched for beginning at the child node
 330  of the found element.
 331  From the example above:
 332 \end_layout
 333
 334 \begin_layout Code
 335
 336 <root>
 337 \end_layout
 338
 339 \begin_layout Code
 340
 341     <child>
 342 \end_layout
 343
 344 \begin_layout Code
 345
 346         <last>
 347 \end_layout
 348
 349 \begin_layout Code
 350
 351 Content or XML CDATA of the "last" element.
 352 \end_layout
 353
 354 \begin_layout Code
 355
 356         </last>
 357 \end_layout
 358
 359 \begin_layout Code
 360
 361     </child>
 362 \end_layout
 363
 364 \begin_layout Code
 365
 366     <child>
 367 \end_layout
 368
 369 \begin_layout Code
 370
 371 This element will never be reached.
 372 \end_layout
 373
 374 \begin_layout Code
 375
 376     </child>
 377 \end_layout
 378
 379 \begin_layout Code
 380
 381 </root>
 382 \end_layout
 383
 384 \begin_layout Standard
 385 The second "child" element is never reached.
 386 \end_layout
 387
 388 \begin_layout Section
 389 Connecting to PWMD
 390 \end_layout
 391
 392 \begin_layout Standard
 393 You will need a
 394 \emph on
 395 pwmd
 396 \emph default
 397  client to send commands to the pwmd server.
 398
 399 \emph on
 400 libpwmd
 401 \emph default
 402  includes a client named
 403 \emph on
 404 pwmc
 405 \emph default
 406 .
 407  It is command-line based and there are not any fancy graphics, but it is
 408  good for understanding how
 409 \emph on
 410 pwmd
 411 \emph default
 412  commands are processed.
 413  If you want a more user friendly client that resembles a file manager and
 414  has a point and click interface, try qpwmc
 415 \begin_inset Foot
 416 status collapsed
 417
 418 \begin_layout Plain Layout
 419 http://qpwmc.sourceforge.net/
 420 \end_layout
 421
 422 \end_inset
 423
 424  which uses the Qt4 toolkit and is also a full featured client.
 425 \end_layout
 426
 427 \begin_layout Standard
 428 In this tutorial we will use the
 429 \emph on
 430 pwmc
 431 \emph default
 432  client included with libpwmd.
 433
 434 \emph on
 435 pwmc
 436 \emph default
 437  has two modes that commands are read from: interactive and stdin.
 438  The interactive mode uses the readline library and has command history
 439  while reading from standard input (stdin) makes shell scripting and automation
 440  easy.
 441  For the examples, we will be connecting to the default local unix domain
 442  socket that pwmd waits for connections on.
 443  Remote connections are possible over TLS or an SSH channel but those are
 444  not covered here.
 445  Read the pwmc(1) manual page for details about how to do that.
 446 \end_layout
 447
 448 \begin_layout Standard
 449 The example filename we will use is "datafile".
 450  It is initially a non-existent file but it will be created once we have
 451  saved to it.
 452  Now let us connect to the server in interactive mode and open the data
 453  file:
 454 \end_layout
 455
 456 \begin_layout Code
 457
 458 $ pwmc datafile
 459 \end_layout
 460
 461 \begin_layout Code
 462
 463 Connected.
 464 \end_layout
 465
 466 \begin_layout Code
 467
 468 pwm>
 469 \end_layout
 470
 471 \begin_layout Standard
 472 The "pwm>" prompt is a readline prompt that has command history and can
 473  do filename completion.
 474  It also is annoying because, as mentioned, elements in element paths are
 475  TAB delimited, but command completion in readline uses the TAB character,
 476  too.
 477  To insert a real TAB character in interactive mode rather than do readline
 478  completion, you will need to first press CTRL-V and then press TAB.
 479 \end_layout
 480
 481 \begin_layout Section
 482 Commands
 483 \end_layout
 484
 485 \begin_layout Standard
 486 There are two different types of commands: client commands and protocol
 487  commands.
 488  The client commands are
 489 \emph on
 490 pwmc
 491 \emph default
 492  specific and only available to the
 493 \emph on
 494 pwmc
 495 \emph default
 496  client.
 497  Protocol commands are commands sent from any client and to the
 498 \emph on
 499 pwmd
 500 \emph default
 501  server.
 502  All pwmc client commands are prefixed with a period '.' followed by the
 503  command name.
 504  Protocol commands are sent without any prefix.
 505  To see the available pwmc and protocol commands, send the HELP command:
 506 \end_layout
 507
 508 \begin_layout Code
 509 pwm> .help
 510 \end_layout
 511
 512 \begin_layout Standard
 513 or
 514 \end_layout
 515
 516 \begin_layout Code
 517 pwm> help
 518 \end_layout
 519
 520 \begin_layout Standard
 521 To store some data in an element path, you will need to know what element
 522  path to create.
 523  It is up to you how you want your data organized.
 524  If for example you will be storing account information it may be good to
 525  categorize what the account is for: email, instant messaging, blogging,
 526  etc.
 527  An application that uses libpwmd may require that a certain element path
 528  exists.
 529  Refer to that applications documentation to determine what element paths
 530  need to be created.
 531 \end_layout
 532
 533 \begin_layout Standard
 534 In the following example we will setup mail server element paths which can
 535  be used for other applications requiring a mail server configuration.
 536  First, lets create the hostname element path:
 537 \end_layout
 538
 539 \begin_layout Code
 540
 541 pwm> STORE
 542 \end_layout
 543
 544 \begin_layout Standard
 545 The STORE command is a
 546 \emph on
 547 pwmd
 548 \emph default
 549  protocol command.
 550  This command, and some other commands, use what is called a
 551 \emph on
 552 server inquire
 553 \emph default
 554  to retrieve data from the client while other commands may retrieve the
 555  data only from the command arguments.
 556  The server inquire will wait for the client to finish sending its data
 557  before completing the command.
 558  When responding to a server inquire in pwmc, pwmc will show a message telling
 559  you that it is waiting for data to be sent.
 560  Enter the element path and its content, then press <CTRL-D> twice to finish
 561  sending the data and to let
 562 \emph on
 563 pwmd
 564 \emph default
 565  complete the command:
 566 \end_layout
 567
 568 \begin_layout Code
 569
 570 pwm> STORE
 571 \end_layout
 572
 573 \begin_layout Code
 574
 575 email<TAB>isp<TAB>IMAP<TAB>hostname<TAB>imap.server.com<CTRL-D><CTRL-D>
 576 \end_layout
 577
 578 \begin_layout Standard
 579 Remember that you should replace <TAB> in the examples with a real TAB character.
 580  I should mention that when sending data via a server inquire there is no
 581  need to press <CTRL-V> to insert the <TAB> character.
 582  That is only needed from the readline command prompt and when not doing
 583  a server inquire.
 584 \end_layout
 585
 586 \begin_layout Standard
 587 After pressing the first <CTRL-D>, the line that was entered is sent to
 588
 589 \emph on
 590 pwmd
 591 \emph default
 592  and the inquire continues.
 593  To terminate the inquire and finish sending data for the command, press
 594  <CTRL-D> a second time.
 595 \end_layout
 596
 597 \begin_layout Standard
 598 If you were to have pressed <RETURN> before any <CTRL-D> then the inquired
 599  line would have been sent in full including a newline character.
 600  Since in this example a newline character in a hostname is not a valid
 601  hostname, this is not what we want.
 602 \end_layout
 603
 604 \begin_layout Standard
 605 We have just created an element path whose XML structure looks like the
 606  following:
 607 \end_layout
 608
 609 \begin_layout Code
 610
 611 <email>
 612 \end_layout
 613
 614 \begin_layout Code
 615
 616     <isp>
 617 \end_layout
 618
 619 \begin_layout Code
 620
 621         <IMAP>
 622 \end_layout
 623
 624 \begin_layout Code
 625
 626             <hostname>imap.server.com</hostname>
 627 \end_layout
 628
 629 \begin_layout Code
 630
 631         </IMAP>
 632 \end_layout
 633
 634 \begin_layout Code
 635
 636     </isp>
 637 \end_layout
 638
 639 \begin_layout Code
 640
 641 </email>
 642 \end_layout
 643
 644 \begin_layout Standard
 645 The GET protocol command returns the value of the last element of an element
 646  path.
 647  To retrieve the hostname of the element path we just created, do:
 648 \end_layout
 649
 650 \begin_layout Code
 651
 652 pwm> GET email<TAB>isp<TAB>IMAP<TAB>hostname
 653 \end_layout
 654
 655 \begin_layout Code
 656
 657 imap.server.com
 658 \end_layout
 659
 660 \begin_layout Standard
 661 Remember that in interactive mode and when not doing a server inquire, you
 662  will need to press <CTRL-V> before pressing <TAB>.
 663 \end_layout
 664
 665 \begin_layout Standard
 666 Let us create the rest of the needed elements:
 667 \end_layout
 668
 669 \begin_layout Code
 670
 671 pwm> STORE
 672 \end_layout
 673
 674 \begin_layout Code
 675
 676 email<TAB>isp<TAB>IMAP<TAB>port<TAB>993<CTRL-D><CTRL-D>
 677 \end_layout
 678
 679 \begin_layout Code
 680
 681 pwm> STORE
 682 \end_layout
 683
 684 \begin_layout Code
 685
 686 email<TAB>isp<TAB>IMAP<TAB>ssl<TAB>1<CTRL-D><CTRL-D>
 687 \end_layout
 688
 689 \begin_layout Code
 690
 691 pwm> STORE
 692 \end_layout
 693
 694 \begin_layout Code
 695
 696 email<TAB>isp<TAB>username<TAB>myusername<CTRL-D><CTRL-D>
 697 \end_layout
 698
 699 \begin_layout Code
 700
 701 pwm> STORE
 702 \end_layout
 703
 704 \begin_layout Code
 705
 706 email<TAB>isp<TAB>password<TAB>mypassword<CTRL-D><CTRL-D>
 707 \end_layout
 708
 709 \begin_layout Standard
 710 Now the element structure for the "email" element looks like this:
 711 \end_layout
 712
 713 \begin_layout Code
 714
 715 <email>
 716 \end_layout
 717
 718 \begin_layout Code
 719
 720     <isp>
 721 \end_layout
 722
 723 \begin_layout Code
 724
 725         <IMAP>
 726 \end_layout
 727
 728 \begin_layout Code
 729
 730               <hostname>imap.server.com</hostname>
 731 \end_layout
 732
 733 \begin_layout Code
 734
 735               <port>993</port>
 736 \end_layout
 737
 738 \begin_layout Code
 739
 740               <ssl>1</ssl>
 741 \end_layout
 742
 743 \begin_layout Code
 744
 745         </IMAP>
 746 \end_layout
 747
 748 \begin_layout Code
 749
 750         <username>myusername</username>
 751 \end_layout
 752
 753 \begin_layout Code
 754
 755         <password>mypassword</password>
 756 \end_layout
 757
 758 \begin_layout Code
 759
 760     </isp>
 761 \end_layout
 762
 763 \begin_layout Code
 764
 765 </email>
 766 \end_layout
 767
 768 \begin_layout Standard
 769 If you wanted to change your password (after changing it on the mail server,
 770  of course) just do as you did when initially creating the password element
 771  path.
 772  The new content will overwrite the existing content:
 773 \end_layout
 774
 775 \begin_layout Code
 776
 777 pwm> STORE
 778 \end_layout
 779
 780 \begin_layout Code
 781
 782 email<TAB>isp<TAB>password<TAB>newpassword<CTRL-D><CTRL-D>
 783 \end_layout
 784
 785 \begin_layout Standard
 786 An application using libpwmd that needs to know mail server information
 787  now has all the information it needs.
 788  The only thing left to do now is to save the changes:
 789 \end_layout
 790
 791 \begin_layout Code
 792
 793 pwm> <CTRL-D>
 794 \end_layout
 795
 796 \begin_layout Standard
 797 After pressing <CTRL-D> a prompt will be shown asking what to do.
 798  Press
 799 \begin_inset Quotes eld
 800 \end_inset
 801
 802 s
 803 \begin_inset Quotes erd
 804 \end_inset
 805
 806  to save what we have created.
 807 \end_layout
 808
 809 \begin_layout Standard
 810 Since this is a new file, you will be prompted for a passphrase to use for
 811  encryption.
 812  Once done, the data file is encrypted and written to disk and the passphrase
 813  is cached in pwmd so you do not need to enter it the next time your data
 814  file is opened or saved.
 815  There are a few pwmd configuration parameters that affect how this operates.
 816  See the
 817 \emph on
 818 pwmd
 819 \emph default
 820  documentation for details.
 821 \end_layout
 822
 823 \begin_layout Section
 824 \begin_inset CommandInset label
 825 LatexCommand label
 826 name "sec:Linking-elements"
 827
 828 \end_inset
 829
 830 Linking elements
 831 \end_layout
 832
 833 \begin_layout Standard
 834 One distinguishing feature of pwmd is the ability to share data of one element
 835  path with another.
 836  If for example your ISP lets you host a blog on their server and you use
 837  a blogging client that can use libpwmd for authentication details, you
 838  can share authentication information with the email example above when
 839  the account details are the same.
 840  When element linking is used, this avoids the need to change the content
 841  for both the blogging and email password elements.
 842 \end_layout
 843
 844 \begin_layout Standard
 845 This is done by setting a special
 846 \begin_inset Quotes eld
 847 \end_inset
 848
 849 target
 850 \begin_inset Quotes erd
 851 \end_inset
 852
 853  attribute for an element.
 854  It behaves similarly to the HTML
 855 \begin_inset Quotes eld
 856 \end_inset
 857
 858 target
 859 \begin_inset Quotes erd
 860 \end_inset
 861
 862  attribute or XML entities or a symbolic link on a filesystem.
 863
 864 \end_layout
 865
 866 \begin_layout Standard
 867 Let's create an example blogging element path:
 868 \end_layout
 869
 870 \begin_layout Code
 871
 872 pwm> STORE
 873 \end_layout
 874
 875 \begin_layout Code
 876
 877 blog<TAB>isp<TAB>hostname<TAB>blog.myisp.com<CTRL-D><CTRL-D>
 878 \end_layout
 879
 880 \begin_layout Code
 881
 882 \end_layout
 883
 884 \begin_layout Code
 885
 886 pwm> ATTR SET target blog<TAB>isp<TAB>username email<TAB>isp<TAB>username
 887 \end_layout
 888
 889 \begin_layout Code
 890
 891 pwm> ATTR SET target blog<TAB>isp<TAB>password email<TAB>isp<TAB>password
 892 \end_layout
 893
 894 \begin_layout Standard
 895 Now each access of the "blog/isp/username" and "blog/isp/password" element
 896  paths, which were created if they did not already exist, will point to
 897  "email/isp/username" and "email/isp/password" respectively.
 898  To retrieve the value or content of an element that contains a "target"
 899  attribute without following any
 900 \begin_inset Quotes eld
 901 \end_inset
 902
 903 target
 904 \begin_inset Quotes erd
 905 \end_inset
 906
 907  attribute, prefix the element with a '!' when specifying it in an element
 908  path.
 909  For example:
 910 \end_layout
 911
 912 \begin_layout Code
 913
 914 pwm> GET blog<TAB>isp<TAB>!password
 915 \end_layout
 916
 917 \begin_layout Code
 918
 919 ERR 536870938: No value
 920 \end_layout
 921
 922 \begin_layout Standard
 923 An error is returned because we have not assigned a value to the literal
 924  element.
 925  A literal element is an element that either contains no "target" attribute
 926  or ignores it by prefixing the element with the mentioned literal element
 927  character '!'.
 928  Let us try storing an example password to the literal element to show usage:
 929 \end_layout
 930
 931 \begin_layout Code
 932
 933 pwmd> STORE
 934 \end_layout
 935
 936 \begin_layout Code
 937
 938 blog<TAB>isp<TAB>!password<TAB>literalpassword<CTRL-D><CTRL-D>
 939 \end_layout
 940
 941 \begin_layout Standard
 942 Now when we redo the previous GET command:
 943 \end_layout
 944
 945 \begin_layout Code
 946
 947 pwm> GET blog<TAB>isp<TAB>!password
 948 \end_layout
 949
 950 \begin_layout Code
 951
 952 literalpassword
 953 \end_layout
 954
 955 \begin_layout Standard
 956 This is the value of the literal password element of the element path.
 957  To follow the element path stored in the "target" attribute, omit the '!'
 958  in the password element.
 959  This will return the
 960 \begin_inset Quotes eld
 961 \end_inset
 962
 963 email/isp/password
 964 \begin_inset Quotes erd
 965 \end_inset
 966
 967  element content:
 968 \end_layout
 969
 970 \begin_layout Code
 971
 972 pwm> GET blog<TAB>isp<TAB>password
 973 \end_layout
 974
 975 \begin_layout Code
 976
 977 mypassword
 978 \end_layout
 979
 980 \begin_layout Standard
 981 A "target" attribute may also refer to another element with a "target" attribute.
 982  Every "target" attribute will be followed until there are no others to
 983  resolve.
 984  To get the real element path and resolve all "target" attributes, use the
 985  REALPATH command:
 986 \end_layout
 987
 988 \begin_layout Code
 989
 990 pwm> REALPATH blog<TAB>isp<TAB>password
 991 \end_layout
 992
 993 \begin_layout Code
 994
 995 !email<TAB>!isp<TAB>!password
 996 \end_layout
 997
 998 \begin_layout Standard
 999 As you can see each element is prefixed with the literal '!' character meaning
1000  that no "target" attribute exists in any element of the resulting element
1001  path.
1002 \end_layout
1003
1004 \begin_layout Standard
1005 Using the LIST command is useful to show the element structure of a document:
1006 \end_layout
1007
1008 \begin_layout Code
1009
1010 pwm> LIST
1011 \end_layout
1012
1013 \begin_layout Code
1014
1015 !email
1016 \end_layout
1017
1018 \begin_layout Code
1019
1020 !blog
1021 \end_layout
1022
1023 \begin_layout Code
1024
1025 pwm> LIST !email
1026 \end_layout
1027
1028 \begin_layout Code
1029
1030 !email
1031 \end_layout
1032
1033 \begin_layout Code
1034
1035 !email<TAB>!isp
1036 \end_layout
1037
1038 \begin_layout Code
1039
1040 !email<TAB>!isp<TAB>!username
1041 \end_layout
1042
1043 \begin_layout Code
1044
1045 !email<TAB>!isp<TAB>!password
1046 \end_layout
1047
1048 \begin_layout Code
1049
1050 !email<TAB>!isp<TAB>!IMAP<TAB>!hostname
1051 \end_layout
1052
1053 \begin_layout Code
1054
1055 !email<TAB>!isp<TAB>!IMAP<TAB>!port
1056 \end_layout
1057
1058 \begin_layout Code
1059
1060 !email<TAB>!isp<TAB>!IMAP<TAB>!ssl
1061 \end_layout
1062
1063 \begin_layout Code
1064
1065 pwm> LIST !blog
1066 \end_layout
1067
1068 \begin_layout Code
1069
1070 !blog
1071 \end_layout
1072
1073 \begin_layout Code
1074
1075 !blog<TAB>!isp
1076 \end_layout
1077
1078 \begin_layout Code
1079
1080 !blog<TAB>!isp<TAB>!username
1081 \end_layout
1082
1083 \begin_layout Code
1084
1085 !blog<TAB>!isp<TAB>username
1086 \end_layout
1087
1088 \begin_layout Code
1089
1090 !blog<TAB>!isp<TAB>!password
1091 \end_layout
1092
1093 \begin_layout Code
1094
1095 !blog<TAB>!isp<TAB>password
1096 \end_layout
1097
1098 \begin_layout Standard
1099 Notice that there are two username and password elements in the
1100 \begin_inset Quotes eld
1101 \end_inset
1102
1103 blog
1104 \begin_inset Quotes erd
1105 \end_inset
1106
1107  element path: each with and without the literal element character prefix.
1108  This shows that both the username and password elements contain a "target"
1109  attribute.
1110 \end_layout
1111
1112 \begin_layout Standard
1113 For the final example, we will remove the
1114 \begin_inset Quotes eld
1115 \end_inset
1116
1117 target
1118 \begin_inset Quotes erd
1119 \end_inset
1120
1121  attribute of the blogging password element:
1122 \end_layout
1123
1124 \begin_layout Code
1125
1126 pwm> ATTR DELETE target blog<TAB>isp<TAB>!password
1127 \end_layout
1128
1129 \begin_layout Standard
1130 If we were to have omitted the '!' from the password element then pwmd would
1131  try to remove the "target" attribute from the "email/isp/password" element
1132  path.
1133  That would return an error because no
1134 \begin_inset Quotes eld
1135 \end_inset
1136
1137 target
1138 \begin_inset Quotes erd
1139 \end_inset
1140
1141  attribute had been set for that element.
1142 \end_layout
1143
1144 \begin_layout Standard
1145 Note that the "blog" and "isp" elements have no literal element character
1146  prepended to them in the example.
1147  It is not needed because they have no
1148 \begin_inset Quotes eld
1149 \end_inset
1150
1151 target
1152 \begin_inset Quotes erd
1153 \end_inset
1154
1155  attribute themselves.
1156 \end_layout
1157
1158 \begin_layout Standard
1159 Using
1160 \begin_inset Quotes eld
1161 \end_inset
1162
1163 target
1164 \begin_inset Quotes erd
1165 \end_inset
1166
1167  attributes can be confusing.
1168  The best way to get the hang of linking elements is to experiment and use
1169  the LIST and DUMP commands to show the document structure.
1170  Remember to use the literal element prefix '!' when you do not want to
1171  follow any "target" attributes.
1172 \end_layout
1173
1174 \end_body
1175 \end_document